SBDB Close-Approach Data API

Version: 1.1 (2016 September)
change log

This API provides access to current close-approach data for all asteroids and comets in JPL’s SBDB (Small-Body DataBase). Defaults for query parameters are setup for a typical CNEOS web-site search: NEO Earth close-approaches less than 0.05 au in the next 60 days sorted by date.

HTTP Request

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

Example Queries

  • get all close-approach data for asteroid 433 Eros within 0.2 au between 1900-Jan-01 and 2100-Jan-01:
    • https://ssd-api.jpl.nasa.gov/cad.api?des=433&date-min=1900-01-01&date-max=2100-01-01&dist-max=0.2
  • get Earth close-approach data for NEOs within 10 lunar distances on or after 2018-Jan-01 sorted by distance
    • https://ssd-api.jpl.nasa.gov/cad.api?dist-max=10LD&date-min=2018-01-01&sort=dist

Query Parameters

Most query parameters are filters effectively limiting the data to those matching the constraints, a few are object selectors (limit data to those matching the specified object), and one is a sort key. Filter-type query parameters are “additive” in that they are combined with logical AND when applied to the data. Boolean-type filter parameters are only applied when true. For example, setting “neo=false” simply disables that filter (it does not select non-NEOs).

Parameter Type Default Function Description
date-min string “now” filter exclude data earlier than this date YYYY-MM-DD or date/time YYYY-MM-DDThh:mm:ss or now for the current date
date-max string “+60” filter exclude data later than this date YYYY-MM-DD or date/time YYYY-MM-DDThh:mm:ss or now for the current date or +D for “D” days after now
dist-min string none filter exclude data with an approach distance less than this, e.g., 0.05, 10LD (default units: au)
dist-max string “0.05” filter exclude data with an approach distance greater than this (see dist-min)
h-min number none filter exclude data from objects with H-values less than this (e.g., 22 meaning objects smaller than this)
h-max number none filter exclude data from objects with H-value greater than this (e.g., 17.75 meaning objects larger than this)
v-inf-min number none filter exclude data with V-infinity less than this positive value in km/s (e.g., 18.5)
v-inf-max number none filter exclude data with V-infinity greater than this positive value in km/s (e.g., 20)
v-rel-min number none filter exclude data with V-relative less than this positive value in km/s (e.g., 11.2)
v-rel-max number none filter exclude data with V-relative greater than this positive value in km/s (e.g., 19)
class string none filter limit data to objects with the specified orbit-class (e.g., ATE; see list of valid class values below)
pha boolean false filter limit data to PHAs
nea boolean false filter limit data to NEAs
comet boolean false filter limit data to comets
nea-comet boolean false filter limit data to NEAs and comets
neo boolean true filter limit data to NEOs
kind string none filter limit data to objects of the specified kind (a=asteriod, an=numbered-asteroids, au=unnumbered-asteroids, c=comets, cn=numbered-comets, cu=unnumbered-comets, n=numbered-objects, and u=unnumbered-objects)
spk int none selector only data for the object matching this SPK-ID (e.g., 2000433 )
des string none selector only data for the object matching this designation (e.g., 2015 AB or 141P or 433) [NOTE: when submitting a des containing a space in your query string, you must replace the space with %20, for example 2015%20AB]
body string “Earth” selector limit data to close-approaches to the specified body (e.g., Earth) or allow all bodies with ALL or *
sort string “date” sorter sort data on the specified field: “date”, “dist”, “dist-min”, “v-inf”, “v-rel”, “h”, or “object” (default sort order is ascending: prepend “-“ for descending)
limit number none filter limit data to the first N results (where N is the specified number and must be an integer value greater than zero)
fullname boolean false output include the full-format object name/designation

Data Output

Please always check the JSON payload “signature” object for the “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.

Successful query requests result in a JSON-format data payload. The specific content depends on the query mode. If a search is too restrictive, it is possible for a zero-count result (see below).

Each CAD record is packaged as an array of fields (corresponding to those listed) in the following order:

  • des - primary designation of the asteroid or comet (e.g., 443, 2000 SG344)
  • orbit_id - orbit ID
  • jd - time of close-approach (JD Ephemeris Time)
  • cd - time of close-approeach (formatted calendar date/time)
  • dist - nominal approach distance (au)
  • dist_min - minimum (3-sigma) approach distance (au)
  • dist_max - maximum (3-sigma) approach distance (au)
  • v_rel - velocity relative to the approach body at close approach (km/s)
  • v_inf - velocity relative to a massless body (km/s)
  • t_sigma_f - 3-sigma uncertainty in the time of close-approach (formatted in days, hours, and minutes; days are not included if zero; example “13:02” is 13 hours 2 minutes; example “2_09:08” is 2 days 9 hours 8 minutes)
  • body - name of the close-approach body (e.g., Earth)
    • only output if the body query parameters is set to ALL
  • h - absolute magnitude H (mag)
  • fullname - formatted full-name/designation of the asteroid or comet
    • optional - only output if requested with the appropriate query flag
    • formatted with leading spaces for column alignment in monospaced font tables

Sample Data Output

Here is an example of the JSON-format output for a query resulting in 2 records for close-approaches to the Earth with a minimum distance of 1LD.

{
  "signature":{"version":"1.1","source":"NASA/JPL SBDB Close Approach Data API"},
  "count":"2",
  "fields":["des","orbit_id","jd","cd","dist","dist_min","dist_max","v_rel","v_inf","t_sigma_f","h","fullname"],
  "data":[
    ["2007 JB21","9","2418800.878283280","1910-May-09 09:05","0.0020925812637796","0.000330379338764904","0.00489001931160697","7.59151917808528","7.4218978450753","00:25","25.4","       (2007 JB21)"],
    ["2012 BX34","16","2419429.176816497","1912-Jan-27 16:15","0.00224445877558233","0.00107169260360805","0.0791138808793694","9.53393503237496","9.40859414806313","1_00:16","27.6","       (2012 BX34)"]
  ]
}

Here’s an example of a zero-count result (e.g., a query is too restrictive).

{
  "signature":{"version":"1.1","source":"NASA/JPL SBDB Close Approach Data API"},
  "count" : "0"
}

SBDB Orbit Class Values

Class Description
IEO Atira An asteroid orbit contained entirely within the orbit of the Earth (Q < 0.983 AU). Also known as an Interior Earth Object.
ATE Aten Near-Earth asteroid orbits similar to that of 2062 Aten (a < 1.0 AU; Q > 0.983 AU).
APO Apollo Near-Earth asteroid orbits which cross the Earth’s orbit similar to that of 1862 Apollo (a > 1.0 AU; q < 1.017 AU).
AMO Amor Near-Earth asteroid orbits similar to that of 1221 Amor (1.017 AU < q < 1.3 AU).
MCA Mars-crossing Asteroid Asteroids that cross the orbit of Mars constrained by (1.3 AU < q < 1.666 AU; a < 3.2 AU).
IMB Inner Main-belt Asteroid Asteroids with orbital elements constrained by (a < 2.0 AU; q > 1.666 AU).
MBA Main-belt Asteroid Asteroids with orbital elements constrained by (2.0 AU < a < 3.2 AU; q > 1.666 AU).
OMB Outer Main-belt Asteroid Asteroids with orbital elements constrained by (3.2 AU < a < 4.6 AU).
TJN Jupiter Trojan Asteroids trapped in Jupiter’s L4/L5 Lagrange points (4.6 AU < a < 5.5 AU; e < 0.3).
CEN Centaur Objects with orbits between Jupiter and Neptune (5.5 AU < a < 30.1 AU).
TNO TransNeptunian Object Objects with orbits outside Neptune (a > 30.1 AU).
PAA Parabolic Asteroid Asteroids on parabolic orbits (e = 1.0).
HYA Hyperbolic Asteroid Asteroids on hyperbolic orbits (e > 1.0).
HYP Hyperbolic Comet Comets on hyperbolic orbits (e > 1.0).
PAR Parabolic Comet Comets on parabolic orbits (e = 1.0).
COM Comet Comet orbit not matching any defined orbit class.
JFC Jupiter-family Comet* Jupiter-family comet, classical definition (P < 20 y).
HTC Halley-type Comet* Halley-type comet, classical definition (20 y < P < 200 y).
ETc Encke-type Comet Encke-type comet, as defined by Levison and Duncan (Tj > 3; a < aJ).
CTc Chiron-type Comet Chiron-type comet, as defined by Levison and Duncan (Tj > 3; a > aJ).
JFc Jupiter-family Comet Jupiter-family comet, as defined by Levison and Duncan (2 < Tj < 3).

Close Approach Bodies

The following bodies may be selected via the body query parameter.

Value Body
Merc Mercury
Venus Venus
Earth Earth
Mars Mars
Juptr Jupiter
Satrn Saturn
Urnus Uranus
Neptn Neptune
Pluto Pluto
Moon Moon

HTTP Response Codes

All errors are returned via appropriate HTTP response codes. Note that it is possible to submit query parameters resulting in no matching data. In such cases, a non-error code of 200 is returned so the user is responsible for checking the payload if they wish to detect a null-result.

HTTP Code Description Typical Usage
200 OK normal successful result: array of CA data returned (may be empty)
400 Bad Request the request contained invalid keywords and/or content or used a request-method other than GET or POST (details returned in the JSON payload)
500 Internal Server Error the database is not available at the time of the request

Change Log

Version 1.1 (2016 September)

  • Updated default values for many query parameters such that the default query (i.e., with no query parameters set) results in data of typical interest (as opposed to dumping the entire data set).

Version 1.0 (2016 August)

  • Initial release