SBDB Query API

Version: 1.0 (2021 August)
change log

The SBDB (Small-Body DataBase) query API provides a method of requesting data for a set of asteroids and/or comets matching specified constraints.

For more information about JPL’s SBDB, see this page from the SSD website.

HTTP Request

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

Example Queries

  • Get orbital elements for all known Atira-class NEAs:
    • https://ssd-api.jpl.nasa.gov/sbdb_query.api?fields=full_name,epoch,e,a,q,i,om,w&sb-class=IEO
  • Determine the number of known numbered periodic comets, not including fragments:
    • https://ssd-api.jpl.nasa.gov/sbdb_query.api?sb-ns=n&sb-kind=c&sb-xfrag=1

ADD EXAMPLES HERE

Query Parameters

Parameter Type Default Allowable Values Mode Description
info string none count,field,all I When count is selected, return the number of objects available in the SBDB. When field is selected, return all available output fields. If all is selected, output count and field results. See “mode” I section below for details.
fields string none see description Q List of fields to be output. If no fields are specified, only the count (number of records matching found) is output. Field names are case-sensitive.
sort string none see description Q Sort results by the specified field(s). Up to three fields can be specified, separated by commas , and descending direction can be specified by prefixing the field name with minus - (ascending is the default).
limit number none see description Q Limit data to the first N results (where N is the specified number and must be an integer value greater than zero).
limit-from number none see description Q Limit data starting from the specified record (where zero is the first record). Useful for “paging” through large datasets. Requires limit. CAUTION: it is possible for the underlying database to change between API calls.
full-prec boolean false true or 1, false or 0 Q output data in full precision (normally, data are returned in reduced precision for display purposes)

Please see SBDB (filter) for additional query parameters.

Query Modes

mode I

Information mode. This mode provides various information about the SBDB and this API.

Setting query parameter info=count returns the current total number of small-bodies in the SBDB grouped by:

  • numbered asteroids
  • unnumbered asteroids
  • numbered comets (includes comet fragments)
  • unnumbered comets (includes comet fragments)

Example output:

"info" : {
   "count" : {
      "au" : "258103",
      "cu" : "3088",
      "cn" : "447",
      "an" : "523584"
   }
}

Setting the query parameter info=field returns all available output fields with units and description for each. Results are grouped by broad categories “Object Fields”, “Orbit and Model Parameter Fields”, and “Physical Parameter Fields”. Partial example output follows:

"info" : {
  "field" : {
    "object" : {
      "field_label" : "Object Fields",
      "list" : [
        {
          "name" : "spkid",
          "title" : "SPK-ID",
          "description" : "object primary SPK-ID",
          "units" : null
        },
        {
          "name" : "full_name",
          "title" : "object fullname",
          "description" : "object full name/designation",
          "units" : null
        },
        ...
      ]
    },
    "orbit" : {
      "field_label" : "Orbit and Model Parameter Fields",
      "list" : [
        {
          "name" : "orbit_id",
          "title" : "orbit ID",
          "description" : "orbit solution ID",
          "units" : null
        },
        {
          "name" : "epoch",
          "title" : "epoch",
          "description" : "epoch of osculation in Julian day form",
          "units" : "TDB"
        },
        {
          "name" : "e",
          "title" : "e",
          "description" : "eccentricity",
          "units" : null
        },
        ...
      ]
    },
    "phys_par" : {
      "field_label" : "Physical Parameter Fields",
      "list" : [
        {
        "name" : "H",
        "title" : "H",
        "description" : "absolute magnitude parameter",
        "units" : null
        },
        {
        "name" : "G",
        "title" : "G",
        "description" : "magnitude slope parameter (default is 0.15)",
        "units" : null
        },
        ...
      ]
    }
  }
}

Please see SBDB (filter) for additional mode I parameters.

mode Q

Normal query mode. This mode provides a list (or count) of small-bodies matching user-specified constraints. When no output fields are requested, a simple total count of the matching small-bodies if returned. Otherwise, a list with user-specified output fields for each matching small-body is returned.

Available SBDB Fields

The following table lists fields available for output from the SBDB. You can select any combination of fields from none to all in any order desired. Any given field may only be specified once (e.g., you cannot request fields=spkid,pdes,a,spkid as spkid is specified more than once).

Field names are case-sensitive.

Field Name Type Description
spkid string primary SPK-ID
full_name string full designation (and name)
kind string indicates whether asteroid (a) or comet (c) and whether numbered (n) or unnumbered (u); for example a value of an indicates a numbered asteroid and cu indicates an unnumbered comet
pdes string primary designation (for numbered asteroids, this is the IAU number); examples: 433, 2016 B1, 1999 AN10
name string IAU name (if any); examples: Ceres, Halley, d'Arrest
prefix string comet prefix: P, C, D (A for asteroids previously designated as comets)
class string orbit classification code
neo boolean flag indicating the object is an NEO (Y or N)
pha boolean flag indicating the object is a PHA (Y or N)
t_jup number Jupiter Tisserand parameter
moid number minimum distance between the orbits of Earth and the small-body (au); use moid.ld for units in lunar distances (LD)
moid_jup number minimum distance between the orbits of Jupiter and the small-body (au)
orbit_id string orbit solution ID
epoch number epoch of osculation in Julian day form (TDB); use epoch.mjd for modified Julian day form; use epoch.cal for calendar form YYYY-MM-DD.D
equinox string equinox of reference frame (e.g., J2000)
e number eccentricity
a number semimajor axis (au)
q number perihelion distance (au)
i number inclination (deg)
om number longitude of the ascending node (deg)
w number argument of perihelion (deg)
ma number mean anomaly (deg)
tp number time of perihelion passage in Julian day form (TDB); use tp.cal for calendar form YYYY-MM-DD.D
per number orbital period (d); use per.y for orbital period in Julian years (y)
n number mean motion (deg/d)
ad number aphelion distance (au)
sigma_e number 1-sigma uncertainty in the eccentricity
sigma_a number 1-sigma uncertainty in the semimajor axis (au)
sigma_q number 1-sigma uncertainty in the perihelion distance (au)
sigma_i number 1-sigma uncertainty in the inclination (deg)
sigma_om number 1-sigma uncertainty in the longitude of the ascending node (deg)
sigma_w number 1-sigma uncertainty in the argument of perihelion (deg)
sigma_tp number 1-sigma uncertainty in the time of perihelion passage (d)
sigma_ma number 1-sigma uncertainty in the mean anomaly (deg)
sigma_per number 1-sigma uncertainty in the period (d)
sigma_n number 1-sigma uncertainty in the mean motion (deg/d)
sigma_ad number 1-sigma uncertainty in the aphelion distance (au)
source string code indicating the source of the orbit: ORB=”JPL orbit file”, MPC:mpn=”MPC numbered asteroid orbit file”, MPC:mpu=”MPC unnumbered asteroid orbit file”, MPC:mp1=”MPC single opposition short-arc orbit file”
soln_date string date/time of orbit determination (YYYY-MM-DD hh:mm:ss, Pacific Local)
producer string name of the person or institution responsible for the orbit determination
data_arc number number of days spanned by the observations used in the orbit determination
first_obs string date of the first observation used in the orbit (YYYY-MM-DD or YYYY-??-?? when only the year is known)
last_obs string date of the last observation used in the orbit (YYYY-MM-DD or YYYY-??-?? when only the year is known)
n_obs_used number total number of observations of all types used in the orbit
n_del_obs_used number number of radar delay observations used in the orbit
n_dop_obs_used number number of radar Doppler observations used in the orbit
two_body string flag indicating a low-precision 2-body dynamic model was used in the OD
pe_used string JPL internal ID of the planetary ephemeris used in the OD
sb_used string JPL internal ID of the small-body ephemeris used in the OD
condition_code string MPC “U” parameter: orbit uncertainty estimate 0-9, with 0 being good, and 9 being highly uncertain
rms number normalized RMS of the observation fit in the OD
A1 number  
A2 number  
A3 number  
DT number  
S0 number  
A1_sigma number  
A2_sigma number  
A3_sigma number  
DT_sigma number  
S0_sigma number  
H number absolute magnitude (magnitude at 1 au from the Sun and the observer)
G number magnitude slope parameter used in the standard asteroid H/G magnitude law
M1 number  
K1 number  
M2 number  
K2 number  
PC number  
H_sigma number  
diameter number effective body diameter (km)
extent string tri(or bi)-axial body dimensions (km)
GM number mass expressed as a product of the mass “M” and gravitational constant “G” (km3/s2)
density number bulk density (g/cm3)
rot_per number body rotation period (synodic) (h)
pole string spin-pole direction in R.A./Dec. (deg)
albedo number geometric albedo
BV number color index B-V
UB number color index U-B
IR number color index I-R
spec_T string Tholen spectral taxonomic classification
spec_B string SMASSII spectral taxonomic classification
diameter_sigma number 1-sigma formal (or estimated) uncertainty in diameter

Although the field id (a string-type field representing an internal object ID) is available, it is intentionally not listed in the above table because its value and format are subject to change without notice. The id field is only provided as a convenient sortable field resulting in objects sorted by first numbered asteroids, then unnumbered asteroids, followed by numbered then unnumbered comets. Either spkid or pdes should be used for permanent IDs of a given object.

Constraints on Fields

Please see SBDB (filter) for details on available user-specified constraints.

Field Definitions

Please see SBDB (filter), section “MODE I”, for available definitions.

HTTP Response Codes

All errors are returned via appropriate HTTP response codes.

HTTP Code Description Typical Usage
200 OK normal successful result for a single object: object data returned (an error message is returned if the object was not found)
400 Bad Request the request contained invalid keywords and/or content: details returned
405 Method Not Allowed the request used an incorrect method (see the HTTP Request section)
500 Internal Server Error the database is not available at the time of the request
503 Service Unavailable the server is currently unable to handle the request due to a temporary overloading or maintenance of the server, which will likely be alleviated after some delay

Change Log

Version 1.0 (2021 August)

  • Initial release