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

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.

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.

Change Log

Version 1.0 (2021 August)

• Initial release