GET /v1/positions — Compute planetary positions in ecliptic or equatorial coordinates.

Positions

Compute geocentric positions for planets, asteroids, and lunar nodes.

Text

GET  /v1/positions
POST /v1/positions

Credit cost: 1

Parameters

Parameter	Type	Required	Default	Description
`datetime`	string	One of `datetime` or `jd`	—	ISO 8601 UTC datetime
`jd`	number	One of `datetime` or `jd`	—	Julian Day in UT1
`bodies`	string	No	`"planets"`	Comma-separated body names, or `"all"`, `"planets"`, `"asteroids"`
`lat`	number	For topocentric	—	Observer latitude in degrees
`lon`	number	For topocentric	—	Observer longitude in degrees
`alt`	number	No	—	Observer altitude in meters
`sidereal`	string	No	—	Ayanamsha name or ID for sidereal positions
`equatorial`	boolean	No	`false`	Return right ascension / declination instead of longitude / latitude
`speed`	boolean	No	`true`	Include daily motion values
`no_nutation`	boolean	No	`false`	Skip nutation correction
`j2000`	boolean	No	`false`	Use J2000 reference frame
`topocentric`	boolean	No	`false`	Apply topocentric correction (requires `lat`, `lon`)
`heliocentric`	boolean	No	`false`	Return heliocentric positions

Calculation flags are endpoint-specific, and an endpoint refuses a flag it does not implement with a 400 invalid_parameter rather than ignoring it. /v1/positions and /v1/chart accept all seven. The chart endpoints accept all but speed, which they always compute — retrograde markers and applying aspects depend on it. /v1/houses accepts sidereal and no_nutation. Every other endpoint accepts none. The rule applies to batch sub-requests too.

A few accepted flags legitimately change nothing: /v1/aspects and /v1/solar-proximity return angles between bodies, and rotating the whole zodiac leaves those angles alone, so a sidereal request returns the same numbers as a tropical one.

Response

Ecliptic (default)

JSON

{
  "data": [
    {
      "body": "sun",
      "longitude": 0.0042,
      "latitude": 0.0001,
      "distance": 0.9960,
      "speed": 1.0096,
      "sign": "Aries",
      "sign_degree": 0.0042,
      "retrograde": false,
      "declination": 0.0012,
      "out_of_bounds": false
    }
  ],
  "meta": { "..." }
}

Field	Type	Description
`body`	string	Body identifier
`longitude`	number	Ecliptic longitude in degrees (0–360)
`latitude`	number	Ecliptic latitude in degrees
`distance`	number	Distance in AU
`speed`	number	Daily motion in degrees/day
`sign`	string	Zodiac sign name
`sign_degree`	number	Degree within the sign (0–30)
`retrograde`	boolean	Whether the body is retrograde
`declination`	number	Declination in degrees
`out_of_bounds`	boolean	Whether declination exceeds the obliquity of date

Declination is not ecliptic latitude

declination is the ecliptic position rotated onto the celestial equator, using the obliquity for the requested date. It is a different quantity from latitude and can differ from it by up to the obliquity — Pallas, for instance, can sit 28° off the ecliptic while its declination is only 6°.

out_of_bounds is computed from declination against that same obliquity, so a body is flagged exactly when it passes beyond the Sun's declination extremes.

In sidereal mode, longitude is reduced by the ayanamsha but declination is not — declination is measured from the celestial equator, which the choice of zodiac does not move.

Equatorial (`equatorial=true`)

A different response shape, not the same fields reinterpreted. There is no longitude or latitude, and no sign, sign_degree, or retrograde — zodiac signs divide the ecliptic, and retrogradation is defined by decreasing ecliptic longitude, so none of them carry over to the equator.

JSON

{
  "data": [
    {
      "body": "sun",
      "right_ascension": 0.028,
      "declination": 0.0012,
      "distance": 0.9960,
      "ra_speed": 1.0096,
      "dec_speed": 0.4012,
      "out_of_bounds": false
    }
  ],
  "meta": { "..." }
}

Field	Type	Description
`body`	string	Body identifier
`right_ascension`	number	Right ascension in degrees (0–360)
`declination`	number	Declination in degrees (−90 to 90)
`distance`	number	Distance in AU
`ra_speed`	number	Right ascension speed in degrees/day
`dec_speed`	number	Declination speed in degrees/day
`out_of_bounds`	boolean	Whether declination exceeds the obliquity of date

Examples

Default planets

Bash

curl "https://api.morphemeris.com/v1/positions?datetime=2024-03-20T12:00:00Z" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

javascript

const res = await fetch(
  "https://api.morphemeris.com/v1/positions?datetime=2024-03-20T12:00:00Z",
  { headers: { Authorization: "Bearer morphemeris_live_YOUR_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.morphemeris.com/v1/positions",
    params={"datetime": "2024-03-20T12:00:00Z"},
    headers={"Authorization": "Bearer morphemeris_live_YOUR_KEY"},
)
data = res.json()

Specific bodies

Bash

curl "https://api.morphemeris.com/v1/positions?datetime=2024-03-20T12:00:00Z&bodies=sun,moon,mars,chiron" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

Sidereal positions (Lahiri ayanamsha)

Bash

curl "https://api.morphemeris.com/v1/positions?datetime=2024-03-20T12:00:00Z&sidereal=lahiri" \
  -H "Authorization: Bearer morphemeris_live_YOUR_KEY"

See Available Bodies for the full list of supported body names.

Positions

On this page