Ephemeris API

The Ephemeris API can be used to generate minute precision ephemeris for minorplanets. Elements may be specified but are not required. When elements are not provided, they will be queried from the database using the closest available elements solution to the requested ephemeris start date. In this case, Right Ascension and Declination error will also be calculated. Both modes use the same underlying ephemeris calculator that supplies ephemeris solutions for https://asteroid.lowell.edu/. All relevant parameters are J2000.

Request

There are modes for requesting ephemeris; with and without elements specified. Both modes use the same endpoint

Endpoint

https://asteroid.lowell.edu/api/ephemeris/generate

Mode 1: Without Elements

Making a request without specifying elements is the simplest way to generate ephemeris.

Arguments

Value Name Units Default Required
asteroid Any asteroid designation Yes
observatory Observatory 3 Digit Code Yes
start-utc Start UTC Date of Ephemeris YYYY-MM-DDThh:mm Current Datetime No
duration-minutes Ephemeris Duration minutes 1440 (1 day) No
step-minutes Ephemeris Step Time minutes 60 (1 hour) No

Example

See Response section for details on response

https://asteroid.lowell.edu/api/ephemeris/generate?asteroid=2020AB&observatory=698&start-utc=2023-10-30T01:30
{
    "arguments": {reflection_of_arguments_used},
    "ephemeris": [{ephemeris1}, {ephemeris2}, ...]
}

Mode 2: With Elements

Elements may be supplied if desired. Note that if any element field is specified then all element fiels are required. The arguemnt list is an extension of the previous section.

In this mode, the covariance matrix required for error calculation is not avaliable. Therefore, when elements are supplied, the ephermeris is calculated and the results will have have ephemeris errors equal to zero.

Value Name Units Default Required
asteroid Any asteroid designation Yes
observatory Observatory 3 Digit Code Yes
start-utc Start UTC Date of Ephemeris YYYY-MM-DDThh:mm Current Datetime No
duration-minutes Ephemeris Duration minutes 1440 (1 day) No
step-minutes Ephemeris Step Time minutes 60 (1 hour) No
a Semi-major axis AU Yes
e Eccentricity Yes
i Inclination degrees Yes
m Mean Anomaly degrees Yes
node Ascending Node degrees Yes
peri Argument of Periapsis degrees Yes
h H Magnitude Yes
epoch Epoch of Elements YYYY-MM-DDThh:mm Yes
g Slope Parameter 0.15 No

Example

See Response section for details on response

https://asteroid.lowell.edu/api/ephemeris/generate?asteroid=1&observatory=698&start-utc=2017-10-30T01:30&a=2.767409&e=0.0756&i=10.6&m=309.9&node=80.3&peri=73.0&h=3.33&epoch=2017-09-04T00:00&g=0.15
{
    "arguments": {reflection_of_arguments_used},
    "ephemeris": [{ephemeris1}, {ephemeris2}, ...]
}

Response

A successful response returns a JSON object with two top level entries: arguements and ephemeris. The arguements section simply states the parameters used to calculate the ephemeris and in most cases will just be a reflection of the request arguements. The ephemeris sections is a list of records for the resulting ephemeris solution. Each record is a step in in time of the request step-minutes.

The ephemeris record contains the following data:

Key Name Units
airmass Airmass
asteroid_altitude Asteorid Altitude degrees
asteroid_hour_angle Hour Angle of Asteroid degrees
asteroid_moon_elongation Elongation Angle of Asteroid to Moon degrees
calendar Calendar Date of Ephemers YYYY-MM-DDThh:mm:ss
dec Declination of Asteroid radians
dec_deg Declination of Asteroid degrees
dec_dms Declination of Asteroid dd:mm:ss
dec_error Error in Declination arcseconds
dec_motion Motion in Declination arcseconds/minute
ecliptic_latitude Ecliptic Latitude degrees
galactic_latitude Galactic Latitude degrees
heliocentric_distance Heliocentric Distance AU
julian_date Julian Date
lunar_phase Lunar Phase degrees
moon_altitude Altitude of Moon degrees
phase_angle Phase Angle of Asteroid degrees
ra Right Ascension radians
ra_deg Right Ascension degrees
ra_error Error in Right Ascension arcseconds
ra_hms Right Ascension hh:mm:ss
ra_motion Motion in Right Ascension arcseconds/minute
solar_elongation Solar Elongation degrees
sun_altitude Altitude of Sun Degrees
topocenter_distance Distance Between Observer and Asteroid AU
uncertainty Ephemeris Position Total Uncertainty arcseconds/minute
v_magnitude Visual Magnitude

Example

https://asteroid.lowell.edu/api/ephemeris/generate?asteroid=1&observatory=698
{
  "arguments": {
    "a": null,
    "asteroid": "1",
    "duration-minutes": 1440,
    "e": null,
    "epoch": null,
    "g": null,
    "h": null,
    "i": null,
    "m": null,
    "node": null,
    "observatory": "698",
    "peri": null,
    "start-utc": "2023-09-01T12:39",
    "step-minutes": 60
  },
  "ephemeris": [
    {
      "airmass": -1.371311274262469,
      "asteroid_altitude": -46.821800392,
      "asteroid_hour_angle": -9.6781819026,
      "asteroid_moon_elongation": 154.15496009,
      "calendar": "2023-09-01T12:39",
      "dec": -0.071165986712,
      "dec_deg": -4.077510683481698,
      "dec_dms": "-04:04:39.0",
      "dec_error": -0.0054794519834,
      "dec_motion": -10.977844674,
      "ecliptic_latitude": 5.6298980613,
      "galactic_latitude": 56.891996367,
      "heliocentric_distance": 2.6633782921,
      "julian_date": 2460189.027083,
      "lunar_phase": 97.01870091,
      "moon_altitude": 23.413081806,
      "phase_angle": 15.756871514,
      "ra": 3.5658845408,
      "ra_deg": 204.3101344187856,
      "ra_error": 0.00069410940896,
      "ra_hms": "13:37:14.4",
      "ra_motion": 85.799703549,
      "solar_elongation": 45.775433513,
      "sun_altitude": -4.6602004615,
      "topocenter_distance": 3.2672349775,
      "uncertainty": 0.0117654861841709,
      "v_magnitude": 8.8877822947
    },
    ...]
}