Horizons Lookup API

Version: 1.1 (2025 March)
change log

Process a user-specified name, designation, SPK-ID, IAU number, MPC packed designation, or other historical alias, and return in a standardized format its primary synonyms and all aliases recognized by JPL’s Horizons system as being linked to publicly available trajectory data.

This API is intended for telescope schedulers and others who need to correlate one of the many object labels typically possible with Horizons output and other sources.

For example, one might request an ephemeris for asteroid “1954 SO1” from Horizons. This API can be used to determine the object also has the (IAU) name “Thetis”, has historical alternate designations of “A916 YF”, “A913 CA”, a historical alternate SPK ID of “2000017”, an MPC 7-character packed designation of “I52H00A”, and that an SPK file request will come back from Horizons with the default name “20000017.bsp”, based on the current primary SPK ID.

HTTP Request

GET https://ssd.jpl.nasa.gov/api/horizons_lookup.api

Example Queries

• Retrieve (In JSON format) all aliases for objects having the designation “2004 MN4”
  • https://ssd.jpl.nasa.gov/api/horizons_lookup.api?sstr=2004%20MN4
• Retrieve (in text format) all aliases for objects containing the string “Halley”:
  • https://ssd.jpl.nasa.gov/api/horizons_lookup.api?sstr=Halley&format=text

Query Parameters

Usage and examples

The sstr parameter can refer to a planet, asteroid, comet, natural satellite, or spacecraft.

The search is space sensitive. For example, sstr='1990MU' will not match.

This API searches two indexes used by Horizons:

1. The “major body” (MB) index. This includes objects whose trajectories are precomputed for one reason or another, typically because they were created using separate off-line software: planets, dynamical points, natural satellites (of both planets and asteroids), spacecraft, and special case objects such as archival small-body solutions consistent with flight project activity. Horizons ephemerides for such ‘major bodies’ are derived from cartesian vectors extracted by reading these pre-defined datafiles.

2. The small-body index (SB). These are asteroids & comets having IAU designations whose latest initial conditions are stored in a database and numerically integrated to other times upon request. The Horizons results are derived from cartesian vectors extracted from that dynamical integration of the latest trajectory solution.

Names are not guaranteed to be unique across all categories of objects. For example, there is an asteroid named “Halley” and a comet named “Halley”, both in the small-body index. A search on sstr=Juno would currently return data for three objects: the Juno spacecraft, the Juno Centaur booster (both in the major-body index) and the asteroid “3 Juno” (in the small-body index).

If the type of object is known, the optional group parameter provides seven limiters to restrict search results to a single type of object and improve the chances of a single unique match to the object of interest:

• ast (asteroids only; checks MB & SB)
• com (comets only; checks MB & SB)
• pln (planets only; checks MB only)
• sat (natural satellites only; checks MB only)
• sct (spacecraft only; checks MB only)
• mb   (search major body (MB) index only)
• sb   (search numerically integrated small-body (SB) index only)

For example, if it is known that only an asteroid was of interest, sstr=Juno&group=ast would return data only for asteroids and not list the spacecraft matches. Conversely, sstr=Juno&group=sct would return only spacecraft entries, not the asteroid.

Similarly, sstr=Halley would check both indexes and return data for the comet AND asteroid (and perhaps any future spacecraft trajectories using that name), whereas sstr=Halley&group=com would return data only for small-body comet matches. sstr=1P, the comet’s designation, would also work to limit results to the small-body comet.

Asteroidal systems, Patroclus as an example, can have three or more entries in the major body index: system barycenter, the primary body, and one or more satellites, their trajectories all stored in datafiles covering predefined earliest-to-latest timespans. There is then typically an additional entry for the object from the small body index. This can be used within Horizons to instead numerically integrate the latest system barycenter solution over arbitrary timespans with additional types of output, such as statistical uncertainties.

Allowable Characters for sstr

The sstr parameter may contain any combination of alphanumeric characters, space, /, ', -, !, =, | and ..

If the sstr parameter contains any space or other URI-reserved characters, URL-encode such characters for reliable results to avoid parsing by the local operating system. Quoting may not be reliable. For example, to search for “1990 MU”, use sstr=1990%20MU.

Symbols occuring in object names that typically require URL-encoding:

Data Output

Please always check the JSON payload “signature” object for the API “version”. If the version does not match the version in this document (at the top), there is no guarantee that the format has not changed.

Example "signature" object with "version" value "1.0": "signature":{"version":"1.0","source":"NASA/JPL ... API"}

A successful query returns results in JSON-format (by default) or text-format if requested, as shown in the example below. A query that does no match any known object is considered successful but will return a result with the JSON “count” keyword set to zero (“0”).

JSON-format results are provided in the JSON “result” array which contains one or more JSON-object for each matching Horizons body.

For plain-text format results, see examples below under the heading Sample text-format Output.

Sample json-format Output

Here is an example of output for a singular match:

https://ssd.jpl.nasa.gov/api/horizons_lookup.api?sstr=2004%20MN4

{
  "signature" : {
    "source" : "NASA/JPL Horizons Lookup API",
    "version" : "1.0"
  },
  "count" : 1,
  "result" : [
    {
      "alias" : [ "3264226", "K04M04N" ],
      "name" : "99942 Apophis",
      "spkid" : "2099942",
      "pdes" : "2004 MN4",
      "type" : "asteroid (integrated barycenter)",
    }
  ]
}

Here is an example of output for multiple matches:

https://ssd.jpl.nasa.gov/api/horizons_lookup.api?sstr=Juno

{
  "signature" : {
    "source" : "NASA/JPL Horizons Lookup API",
    "version" : "1.0"
  },
  "count" : 3,
  "result" : [
    {
      "name" : "Juno (spacecraft)",
      "pdes" : null,
      "spkid" : "-61",
      "type" : "spacecraft",
      "alias" : []
    },
    {
      "name" : "Juno Centaur Stage (spacecraft)",
      "pdes" : null,
      "spkid" : "-610",
      "type" : "spacecraft",
      "alias" : []
    },
    {
      "name" : "3 Juno",
      "pdes" : "A804 RA",
      "spkid" : "20000003",  
      "type" : "asteroid (integrated barycenter)",
      "alias" : [ "I04R00A" ]
    }
  ]
}

Here is an example of output for no matching objects:

https://ssd.jpl.nasa.gov/api/horizons_lookup.api?sstr=ZZZZ

{
  "signature" : {
    "source" : "NASA/JPL Horizons Lookup API",
    "version" : "1.0"
  },
  "count" : "0"
}

Sample text-format Output

Note that records are delimited by a trailing blank line.

Here is an example of output for a singular match (SB index):

https://ssd.jpl.nasa.gov/api/horizons_lookup.api?sstr=2004%20MN4&format=text

API VERSION: 1.0
API SOURCE: NASA/JPL Horizons Lookup API

Object name        = 99942 Apophis
Type               = asteroid (integrated barycenter)
Primary SPKID      = 20099942
Primary designation= 2004 MN4
Aliases            = 3264226, 2099942, K04M04N

Here is an example of output for multiple matches (MB and SB indexes):

https://ssd.jpl.nasa.gov/api/horizons_lookup.api?sstr=Patroclus&format=text

API VERSION: 1.0
API SOURCE: NASA/JPL Horizons Lookup API

Object name        = Patroclus (system barycenter)
Type               = asteroid barycenter
Primary SPKID      = 20000617
Primary designation= 
Aliases            = 

Object name        = Patroclus (primary body)
Type               = asteroidal system primary
Primary SPKID      = 920000617
Primary designation= 
Aliases            = 

Object name        = Menoetius
Type               = asteroidal system satellite
Primary SPKID      = 120000617
Primary designation= Patroclus I
Aliases            = 

Object name        = 617 Patroclus
Type               = asteroid (integrated barycenter)
Primary SPKID      = 20000617
Primary designation= A906 UL
Aliases            = 1962 NB, 1941 XC, 2000617, J06U00L

Here is an example of output for no matching objects:

https://ssd.jpl.nasa.gov/api/horizons_lookup.api?sstr=ZZZZ&format=text

API VERSION: 1.0
API SOURCE: NASA/JPL Horizons Lookup API

NOTICE: no matches found

HTTP Response Codes

Successful matches return one or more entry listings. Error messages and equivalent integer codes are returned otherwise, as described below.

It is possible to submit a search that produces no matching data. In such cases, a 200 error code is returned but the JSON “count” keyword has a value of “0”.

Change Log

Version 1.1 (2025 March)

• Expanded group specification options and added ‘type’ output

Version 1.0 (2021 September)

• Initial release