SBDB API

Version: 1.3 (2021 September)
change log

The SBDB (Small-Body DataBase) API provides a method of requesting machine-readable data for a specified small body within JPL’s SSD/CNEOS Small-Body DataBase (SBDB). The SBDB contains object identification and naming information, orbital data, and selected physical data for all known asteroids and comets within the solar system. A rich set of ancillary data, such as close approach and virtual impactor information, are also available through this API.

Orbits for almost all the small bodies in the SBDB are computed by JPL’s Solar System Dynamics (SSD) group. Those computations use high-precision dynamical and measurement models, based on the most up-to-date set of observational data published by the Minor Planet Center (MPC), including radar astrometry when available, and using sophisticated data weighting schemes and data editing algorithms.

For more information about JPL’s SBDB, see the SBDB Lookup Tool on the SSD website.

HTTP Request

GET https://ssd-api.jpl.nasa.gov/sbdb.api

Example Queries

• https://ssd-api.jpl.nasa.gov/sbdb.api?sstr=2015ab
• https://ssd-api.jpl.nasa.gov/sbdb.api?sstr=Eros
• https://ssd-api.jpl.nasa.gov/sbdb.api?spk=2000433&phys-par=1
• https://ssd-api.jpl.nasa.gov/sbdb.api?des=73P&alt-des=1&cd-epoch=1
• https://ssd-api.jpl.nasa.gov/sbdb.api?des=2009%20FD&neo=1

Query Parameters

One, and only one, of the following query parameters is required: sstr, spk, or des. All other parameters are optional.

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 valid SBDB API query returns one of the following:

• data for the requested object, if the object was unambiguously specified
• a list of objects matching the non-unique object specification
• a message indicating that no object was found that matched the request

NEOs-Only Mode

To support NEOs-only use cases, a NEO-filter (query parameter neo) is available to limit results to NEOs. This mode supports an additional option which returns limited data on all matching non-NEOs, allowing the client to redirect to a new API call (if required) without setting the neo parameter.

See the next section for an example with neo=2.

Multiple Objects Matching sstr

For normal cases where the query matches a single object, the complete data set from the SBDB is returned in JSON-format. See the next section for details on the data provided.

In cases where more than one object matches, a list is returned with a primary designation pdes and corresponding full-name for each matching object. From pdes, it should be possible to submit a new query with des set to the pdes of interest. Here’s an example result from the query sstr=141P.

{
  "signature":{"version":"1.0","source":"NASA/JPL Small-Body Database (SBDB) API"},
  "code": 300,
  "message": "specified query matched more than one object",
  "list": [
    { "pdes": "141P", "name": "141P/Machholz 2" },
    { "pdes": "141P-A", "name": "141P/Machholz 2-A" },
    { "pdes": "141P-D", "name": "141P/Machholz 2-D" }
  ]
}

A user who wanted only the parent comet 141P could parse this list and submit a new request specifying des=141P which will match only the parent.

Similarly, for neo=2 results matching one or more non-NEO, a list of matching objects is returned. In addition to pdes and name, the perihelion distance q, Earth MOID moid, and orbital class code class are returned. For example, the query sstr=2016%20AA3%2A&neo=2 (where 2016%20AA3%2A is the URL-encoded form of “2016 AA3*”) might result in the following:

{
  "signature":{"version":"1.0","source":"NASA/JPL Small-Body Database (SBDB) API"},
  "info" : "specified object matched one or more non-NEO: see list",
  "count" : 4,
  "list" : [
    {
       "pdes" : "2016 AA30",
       "q" : "2.57",
       "name" : "(2016 AA30)",
       "moid" : "1.57",
       "class" : "MBA"
    },
    {
       "pdes" : "2016 AA33",
       "q" : "1.88",
       "name" : "(2016 AA33)",
       "moid" : "0.887",
       "class" : "MBA"
    },
    {
       "pdes" : "2016 AA35",
       "q" : "2.91",
       "name" : "(2016 AA35)",
       "moid" : "1.93",
       "class" : "MBA"
    },
    {
       "pdes" : "2016 AA36",
       "q" : "2.12",
       "name" : "(2016 AA36)",
       "moid" : "1.13",
       "class" : "MBA"
    }
  ]
}

Normal Data Payload

This output is the result of specifying a unique object.

The following example query https://ssd-api.jpl.nasa.gov/sbdb.api?sstr=Eros returns the following payload containing data sections object and orbit.

{
  “signature": { "source":"NASA/JPL Small-Body Database (SBDB) API", "version":"1.0" },
  "object": {
    "shortname":"433 Eros",
    "neo":true,
    "orbit_class": { "name":"Amor", "code":"AMO" },
    "pha":false,
    "spkid":"2000433",
    "kind":"an",
    "orbit_id":"614",
    "fullname":"433 Eros (1898 DQ)",
    "des":"433",
    "prefix":null
  },
  "orbit": {
    "source":"JPL",
    "cov_epoch":"2451960.5",
    "moid_jup":"3.29",
    "t_jup":"4.583",
    "condition_code":"0",
    "not_valid_before":null,
    "model_pars":[],
    "rms":"0.36",
    "orbit_id":"614",
    "producer":"Otto Matic",
    "first_obs":"1963-07-15",
    "soln_date":"2018-05-29 06:21:04",
    "two_body":null,
    "epoch":"2458200.5",
    "elements": [
      { "value":"0.223", "sigma":"1.2e-08", "name":"e", "title":"eccentricity", "label":"e", "units":null },
      { "value":"1.46", "sigma":"4.8e-10", "name":"a", "title":"semi-major axis", "label":"a", "units":"au" },
      { "value":"1.13", "sigma":"1.8e-08", "name":"q", "title":"perihelion distance", "label":"q", "units":"au" },
      { "value":"10.8", "sigma":"2.8e-06", "name":"i", "title":"inclination", "label":"i", "units":"deg" },
      { "value":"304", "sigma":"1.2e-05", "name":"om", "title":"longitude of the ascending node", "label":"node", "units":"deg" },
      { "value":"179", "sigma":"1.3e-05", "name":"w", "title":"argument of perihelion", "label":"peri", "units":"deg" },
      { "value":"183", "sigma":"5.7e-06", "name":"ma", "title":"mean anomaly", "label":"M", "units":"deg" },
      { "value":"2458516.099", "sigma":"1e-05", "name":"tp", "title":"time of perihelion passage", "label":"tp", "units":"TDB" },
      { "value":"643", "sigma":"3.1e-07", "name":"per", "title":"orbital period", "label":"period", "units":"d" },
      { "value":"0.56", "sigma":"2.7e-10", "name":"n", "title":"mean motion", "label":"n", "units":"deg/d" },
      { "value":"1.78", "sigma":"5.8e-10", "name":"ad", "title":"aphelion distance", "label":"Q", "units":"au" }
    ],
    "equinox":"J2000",
    "data_arc":"20041",
    "not_valid_after":null,
    "n_del_obs_used":"1",
    "sb_used":"SB431-N16",
    "n_obs_used":"6090",
    "comment":null,
    "last_obs":"2018-05-28",
    "pe_used":"DE431",
    "moid":"0.148",
    "n_dop_obs_used":"3"
  }
}

Sections Output

The following sections are available for output. The “object” section is always output. The “orbit” section is output unless specifically excluded by setting query parameter no-orbit=1. All other sections are output only when explicitly requested via the appropriate query parameter, described in table below.

Structure of Sections

The following shows the JSON structure of a normal data payload containing all possible sections. The detailed structure of the contents within each section are described in corresponding document sections below. For example, see the Object Subsection for details on the object fields ... data structure.

"object": {
  object fields ...
},
"orbit": {
  default orbit fields ...
},
"alt_orbits": [
  {
    first alternate (non-default) orbit fields ...
  },
  {
    second alternate (non-default) orbit fields ...
  },
  ...
],
"orbit-defs": {
  { first orbit parameter definition object },
  ...
  { last orbit parameter definition object }
},
"sat": [
  { satellite record fields ... },
  ...
],
"phys_par": [
  { physical parameter fields ... },
  ...
],
"ca_data": [
  { close approach record fields ... },
  ...
],
"radar_obs": [
  { radar obs record fields ... },
  ...
],
"vi_data": [
  { vi record fields },
  ...
],
"discovery": {
  discovery data fields ...
}

Object Data Section

The object data section contains general information about the small body, such as its general category (asteroid or comet, numbered or unnumbered), IAU number, primary and alternate provisional designations, SPK identifier, orbit class, etc.

The following fields are provided in the object section:

If alternate designations are requested (alt-des=1), the field “des_alt” will contain an array of alternate designations in reverse chronological order, or an emtpy array if no alternates are available. Each element in the array contains one or more key/value pair where the key is one of the following:

For example, here is the “des_alt” content for numbered asteroid 5000 IAU:

[
  { "des":"1989 EA11" },
  { "pri":"1987 QN7" },
  { "des":"1979 UK1" }
]

Numbered asteroid 7968 Elst-Pizarro has a dual classification as comet 133P/Elst-Pizarro:

[
  { "pri":"1996 N2" },
  { "des":"1979 OW7" },
  { "com":"133P" }
]

Here is the “des_alt” content for unnumbered asteroid 2002 GU191:

[
  { "des":"2015 FE344" },
  { "des":"2010 JE129" },
  { "des":"2008 CO93" },
  { "des":"2005 VP12" }
]

Numbered comet 1P/Halley has a long list of alternate designations, and its “des_alt” partial (not all designations included) content is as follows:

[
  { "des":"1P/1982 U1","rn":"1986 III","yl":"1982i" },
  { "des":"1P/1909 R1","rn":"1910 II","yl":"1909c" },
  ...
  { "des":"1P/1682 Q1","rn":"1682" },
  ...
  { "des":"1P/  66 B1","rn":"66" },
  ...
  { "des":"1P/-239 K1","rn":"-239" }
]

Here is an example of “des_alt” content for unnumbered comet C/2001 C1:

[
  { "des":"C/2000 HR81" }
]

If ancillary data sets are requested via query parameter anc_data, a list of available data sets is returned. For each data set, count represents the number of data records available (for NHATS data, count indicates the number of viable trajectories) and ref_url points to a webpage describing the data set. Any or all of the following data sets could be included:

• close approach data (ca_data)
• radar astrometry data (ra_data)
• Sentry virtual impactor (VI) data (vi_data)
• NHATS data (nhats_data)

Here is an example of the anc_data object field:

{
  "ca_data" : { "count" : 12, "ref_url" : "https://cneos.jpl.nasa.gov/ca/" },
  "ra_data" : { "count" : 4, "ref_url" : "https://ssd.jpl.nasa.gov/sb/radar.html" },
  "vi_data" : { "count" : 1, "ref_url" : "https://cneos.jpl.nasa.gov/sentry/" },
  "nhats_data" : { "count" : 3302718, "ref_url" : "https://cneos.jpl.nasa.gov/nhats/" },
}

Orbit Data Section

It is assumed the user has a basic understanding of osculating orbital elements. Definitions of elements (for example, “perihelion distance”) can be found in the appropriate literature.

The orbit data section contains information about the orbit of the small body, including:

• estimated orbit parameters with uncertainties
• full covariance information on the primary orbit parameters (optional)
• orbit-related quantities (e.g. MOID: minimum orbital intersection distance, orbit condition code, etc.)
• information about the set of observations upon which the orbit estimate is based (data arc, number of observations, etc.)
• information about the models used for the orbit determination (dynamical model parameters, perturbing body ephemerides, etc.)
• orbit solution information (solution identifier, date/time of solution, producer, comment)

Note that almost all of the orbits in the JPL SBDB are computed by the JPL’s Solar System Dynamics (SSD) group and will therefore have a “source” of JPL and a JPL-assigned “orbit_id”, which for asteroids is usually a simple integer.

The contents of the orbit data section are as follows (the entry in the Optional column indicates the request parameter that controls the field):

By default, not_valid_before and not_valid_after fields (when not null) are output in their original format (either Julian date or calendar date/time where the time may be fractional days or time). If nv-fmt=jd, output is formatted as Julian date. If nv-fmt=cd output is formatted as calendar date/time YYYY-MMM-DD hh:mm.

Orbit Subsection: elements

The elements field is an array of data objects, one for each orbital element. These elements parameterize the heliocentric orbit of the small body measured with respect to the Earth-mean-ecliptic frame at the equinox specified in the orbit field equinox (e.g., “J2000”).

The returned orbital elements are “osculating”, which means they apply at a particular time called the “epoch”; this field is output in the orbit data section (see above). The default epoch used for orbital elements returned by the SBDB API is the “standard MPC epoch”. But elements are also available at the JPL “solution epoch”, which is usually different. Elements will be returned at this epoch if the soln-epoch parameter is set in the SBDB API request. Note that the orbital element uncertainties reported in the sigma field refer to the same epoch as the elements. On the other hand, covariance data, requested by setting the cov request parameter, is only available at the solution epoch (see covariance subsection below).

The orbital elements returned by the SBDB API are as follows:

Only the first 6 of these elements are returned if the epoch is not the standard MPC epoch.

The data object for each orbital element has the following fields:

By default, the API returns data values in reduced precision, generally 3 significant digits (or 3 decimal digits for tp), and sigmas use 2 significant digits. If the full-prec parameter is specified in the API request, all data values are returned in full precision (16 significant digits).

Orbit Subsection: model_pars

The model_pars field is an array of data objects defining the orbit model parameters. These include the non-gravitational parameters for comets, modeling the rocket-like forces due to outgassing (e.g., “A1”, “A2”, etc.). Most asteroids do not use model-pars. A model parameter can be treated in one of 3 ways, as indicated by the kind field:

• set to a fixed, exact value,
• estimated as part of the orbit solution, or
• set to a fixed value with fixed uncertainty, which is “considered” when estimating the other parameters.

The data object for each model parameters has the following fields:

Orbit Subsection: covariance

This data object provides the covariance matrix (or square root thereof) for the orbital elements and estimated model parameters. This subsection is only included when the cov parameter is set in the API request. In the few rare cases when no covariance is available in the SBDB, this subsection is null. The form used for the covariance matrix is determined by the parameter value, as follows: The covariance matrix will be in one of the following forms selected by the cov query parameter:

• cov=mat selects full matrix covariance; units: au, deg, d
• cov=vec selects upper-triangular vector-stored covariance; units: au, deg, d
• cov=src selects upper-triangular vector-stored square-root covariance; units: au, rad, d

Here, “upper-triangular vector-stored” indicates that only the elements of the upper-triangular portion of the square matrix are returned, and they are listed in column-major order. In other words, if the matrix elements are denoted as (row,column), they are specified in the order (1:1), (1:2), (2:2), (1:3), (2:3), (3:3), and so on. The contents of “covariance” data item are:

The dimension of the covariance matrix is usually 6x6 for asteroids, although it is sometimes 7x7 or more. The matrix is often 8x8 for comets because of the estimated non-gravitational parameters. The dimension can be inferred from the length of the labels array.

If the elements field is output, it will be an array of 6 osculating elements at the solution epoch, as described in the parent data object.

Satellite Data (sat) Section

The satellite data section is included in the output if requested via the sat request parameter. This section is an array of data objects, one for each satellite of the selected small-body (a.k.a. primary body).

The contents of the data object for each satellite record are as follows:

Note that any field above (other than fullname, prov_des and year) may be null indicating its value is not known or not yet defined. When iau_num is null, fullname will be the same as prov_des. In cases where there is no known satellite orbit, the orbit object will be empty ({}).

Satellite Orbit Subsection: orbit

The contents of the data object for each satellite orbit record are as follows. The object key is the orbit ID oid.

Satellite Subsection: elements

The elements field is an array of data objects, one for each satellite orbital element. These elements parameterize the bodycentric orbit of the small body measured with respect to the Earth-mean-ecliptic frame EC or the body-equatorial frame EQ at the equinox specified in the field equinox (e.g., “J2000”).

The satellite orbital elements returned by the SBDB API are as follows:

For many satellite orbits, only a few (perhaps even only one) parameter is known. Elements without known values will have the value field set to null. Similarly, very view orbits will have known uncertainties for their parameters so in almost all cases, the sigma field (see below) will be null. Note also that the units for semi-major axis and perihelion distance are in meters (m) instead of au.

The data object for each satellite orbital element has the following fields:

Physical Parameters (phys_par) Section

The physical parameters data section contains information about the physical parameters of the small body, such as the absolute magnitude parameters H and G, diameter, rotation period, spectral class, etc. This information is collected from external sources and provided in the SBDB for reference, and for use in the SBDB Query API.

The contents of the physical parameters data section are as follows:

Close Approach Data Section

The close approach data section ca_data is included if requested via the ca-data request parameter. This section is an array of data objects, one for each close approach that the small body makes to the Earth, the Moon or any of the other planets. Specifically, these are the close approaches of the small body on its nominal orbit integrated forwards and backwards in time. Various quantities are computed at each close approach, such as the time and close approach distance, and the 1-sigma formal uncertainties in these quantities are also computed and made available.

Close approaches are only included in the list if they are reasonably certain. Specifically, close approaches with 3-sigma time uncertainty greater than 10 days or 3-sigma nominal-distance uncertainty greater than 0.1 au are excluded. Since uncertainties typically grow with time away from epoch, this filter puts an implicit limit on the time period over which the close approaches are listed. The start time of the list goes back as far as the year 1900, but the forward time limit is mostly determined by the uncertainties.

The contents of the data object for each close approach are listed in the following table. Fields listed as Optional in this table are controlled by the listed request parameter. If they are desired, the date/times of the close approaches can be requested, either as Julian dates (jd) or calendar dates (cd), or both, via the ca-time query parameter defined above. The close approach time uncertainties are always output, either in minutes or in a ‘d:hh:mm’ format, or both, according to query parameter ca-tunc (see query parameters above). If the close approach uncertainty ellipse parameters are desired, they are requested via query parameter ca-unc.

Close Approach Bodies

The list of close approaches can be restricted to only those for a selected body (e.g. Earth) by specifying that body using the ca-body query parameter; the recognized body names are shortened to 5 characters:

Radar Astrometry Data Section

The radar astrometry data section is included in the output if requested via the radar-obs request parameter. This section is an array of data objects, one for each radar astrometric measurement used in the JPL/SSD orbit solution. These data are provided to the JPL Solar System Dynamics group (https://ssd.jpl.nasa.gov/) by the JPL radar group.

The contents of the data object for each radar measurement are as follows:

VI (Virtual Impactor) Data Section

The Virtual Impactor data section summarizes the potential Earth impacts found by JPL’s Sentry impact monitoring system (https://cneos.jpl.nasa.gov/sentry/) for the selected small body. This section is included in the output only if requested via the vi-data request parameter. The section consists of an array of data objects, one for each potential impact found for the small body.

The contents of the data object for each potential impact are as follows:

Discovery Data Section

The discovery data section discovery provides information about the discovery circumstances of the small body, if available. This section is included only if requested via the discovery request parameter (see above). This information is only available for numbered asteroids and numbered comets. The official IAU name citation is provided only for asteroids, and it is not available for most asteroids named before discovery data became machine readable.

The contents of the discovery data section are as follows:

By default, the citation field contains HTML special characters, as needed. But if the raw-citation query parameter is set, the API returns the original LaTex-like markup as published by the MPC in their plain text format distribution of their monthly circulars.

HTTP Response Codes

All errors are returned via appropriate HTTP response codes.

Change Log

Version 1.3 (2021 September)

• Additional output fields available in VI Data Section

Version 1.2 (2020 January)

• Added query parameter sat (see Query Parameters section and Satellite Section for details)

Version 1.1 (2018 August)

• Added query parameter cd-tp (see Query Parameters section for details)

Version 1.0 (2018 July)

• Initial release