🌐Positions
Where the Sun, the Moon and the planets are
Returns where each requested body appears from the observer's location, sampled between two instants.
One request covers as many bodies and as many instants as needed. Omit bodies to get all of them; set step to sample more finely than once a day.
Returns where each requested body appears from the observer's
location, sampled from from to to at intervals of step.
Sampling is the main thing v3 adds. v2 could only return one
position per day at a fixed time of day; step accepts any ISO
8601 duration, so an altitude curve is one request rather than
twenty-four.
The application key, sent as Authorization: Bearer <key>. Keys are
never accepted in the query string, where they would be recorded in
logs and browser history.
Latitude of the observer, in degrees, positive north.
51.4779Longitude of the observer, in degrees, positive east.
-0.0015Height of the observer above sea level, in metres. Defaults to sea level. The upper bound covers the highest permanent observatories.
0First instant to sample, as an ISO 8601 date or date-time. A bare date means midnight UTC on that date.
2024-06-21T00:00:00ZLast instant to sample. Must not precede from.
2024-06-22T00:00:00ZInterval between samples, as an ISO 8601 duration. P1D reproduces
v2's one-sample-per-day behaviour, which is the default.
P1DExample: PT1HPattern: ^P(?!$)(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$IANA zone the returned instants are expressed in. auto derives it
from the observer's coordinates, which is what v2 always did and
remains the default. UTC is the unambiguous choice.
autoExample: autoWhether to measure from the observer's own position or from the centre of the Earth. The difference is parallax, worth up to about a degree for the Moon and arcseconds for the planets.
topocentricPossible values: Whether the altitude accounts for the atmosphere bending light near
the horizon. none gives the geometric altitude.
standardPossible values: Optional extras, comma separated. formatted adds a parallel block
of sexagesimal strings for each angle, which v2 always sent whether
or not the caller wanted them.
formattedMost samples to return per body before paginating.
1000Opaque cursor from meta.sampling.nextCursor.
Positions for each requested body.
The request could not be parsed.
The application key was missing or not recognised.
The request was understood but a parameter was unacceptable.
GET /api/v3/positions?latitude=51.4779&longitude=-0.0015&from=2024-06-21T00%3A00%3A00Z&to=2024-06-22T00%3A00%3A00Z HTTP/1.1
Host: api.astronomyapi.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"meta": {
"observer": {
"latitude": 51.4779,
"longitude": -0.0015,
"elevation": 0
},
"timezone": "Europe/London",
"units": {
"rightAscension": "hours",
"declination": "degrees",
"altitude": "degrees",
"azimuth": "degrees",
"distance": "au"
},
"frames": {
"equatorial": "J2000",
"horizontal": "apparent, refracted"
},
"sampling": {
"from": "2024-06-21T11:00:00Z",
"to": "2024-06-21T11:00:00Z",
"step": "PT1H",
"count": 1
}
},
"data": [
{
"body": {
"id": "mars",
"name": "Mars"
},
"samples": [
{
"time": "2024-06-21T11:00:00Z",
"rightAscension": 2.44012,
"declination": 13.41983,
"altitude": 41.26454,
"azimuth": 232.99871,
"distance": {
"au": 1.7782248,
"km": 266018470.2
},
"constellation": {
"abbreviation": "Ari",
"name": "Aries"
},
"elongation": 51.52915,
"magnitude": 1.00953
}
]
}
]
}Examples
Mars right now, from London:
The Moon's altitude every fifteen minutes through a night, in UTC:
Everything visible, once a day for a week, with sexagesimal strings alongside the numbers:
Notes
earth is not available here. Seen from the Earth it is at zero distance and has no direction, so v2's answer for it was arbitrary. Asking for it returns 422.
Altitude may be negative. A body below the horizon is a legitimate answer, not an error. Filter on altitude > 0 if only what is up matters.
Refraction is applied by default, because that is where a body appears rather than where it geometrically is. Pass refraction=none for the geometric altitude. The difference is about half a degree at the horizon and negligible overhead.
Large spans paginate. With a fine step a long span can run to tens of thousands of samples; when limit is reached, meta.sampling.nextCursor carries the continuation.
Last updated