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

Positions

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

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

Response

Ecliptic (default)

{
  "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 ecliptic obliquity

Equatorial (`equatorial=true`)

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

Examples

Default planets

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

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();

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

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)

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