Small-Body Radar Astrometry API

Version: 1.0 (2021 June)
change log

The small-body radar astrometry API provides a method of requesting specific records from the available data-set for asteroids and/or comets. Every successful query will return content representing one or more radar astrometry data record. See the SSD page on radar astrometry for details on this data-set.

HTTP Request

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

Example Queries

  • https://ssd-api.jpl.nasa.gov/sb_radar.api (return all available data)
  • https://ssd-api.jpl.nasa.gov/sb_radar.api?kind=c (return data only for comets)
  • https://ssd-api.jpl.nasa.gov/sb_radar.api?des=433 (return data only for 433 Eros)
  • https://ssd-api.jpl.nasa.gov/sb_radar.api?kind=an&coords=1 (return data for numbered asteroids with station coordinates)

Query Parameters

Parameter Type Default Function Description
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., 2004 VB or 45P or 433) [NOTE: when submitting a des containing a space in your query string, you must replace the space with %20, for example 2004%20VB]
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)
bp string none filter select data matching the specified measurement reference (bp): P (peak power) or C (center of mass)
type string none filter select data matching the specified measurement type: R for delay or P for Doppler
observer boolean false output include the observer field in each record
notes boolean false output include the notes field in each record
ref boolean false output include the ref field in each record
fullname boolean false output include the full-format object name/designation
modified boolean false output include the modified field in each record
coords boolean false output include station coordinates for all stations used in the requested data (see Radar Stations below)
c-coords boolean false output if coords is set, output cylindrical station coordinates instead of geodetic coordinates (see Radar Stations below)

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"}

Data are returned in JSON format as a single object (hash-table). The number of records contained in the object is indicated in the “count” key. In cases where the user-specified constraints are too tight (no matching results), only the “count” and “signature” keys are returned, as in the following example.

{ "count":0, "signature":{"version":"1.0","source":"NASA/JPL Small-Body Radar Astrometry API"} }

Each record is provided as an element of the “data” object and each record is an array of fields. The names of each field contained in each record is provided in the “fields” object array. Records are sorted first by object (in order by group: unnumbered comets, numbered comets, unnumbered asteroids, and numbered asteroids) then by measurement in reverse chronological order.

The fields are defined as follows.

Field Optional Description
des   primary designation of the asteroid or comet (e.g., 443, 2019 NX1, 45P)
epoch   epoch of the measurement (UTC, YYYY-MM-DD hh:mm:ss)
value   radar delay or Doppler measurement in units specified in the units field
sigma   estimated 1-sigma uncertainty of the measurement
units   units associated with the radar measurement: us (microseconds) for delay and Hz (hertz) for Doppler measurements
freq   Frequency of the transmitter (MHz)
rcvr   station code for the radar receiver (see Radar Stations section below)
xmit   station code for the radar transmitter (see Radar Stations section below)
bp   measurement reference (i.e., bounce point) with possible values of P (peak power) and C (center of mass)
observer observer list of observers
notes notes notes specific to the measurement
ref ref publication reference (if any), see the section below
fullname fullname formatted full-name/designation of the asteroid or comet
modified modified date/time when the record was last modified (Pacific time, YYYY-MM-DD hh:mm:ss)

Sample Data Output

{
  "signature" : {"source" : "NASA/JPL Small-Body Radar Astrometry API", "version" : "1.0"},
  "count" : "3",
  "fields" : [ "des","epoch","value","sigma","units","freq","rcvr","xmit","bp" ],
  "data" : [
    [
      "1997 WQ23",
      "2013-11-22 01:53:00",
      "111982347.7",
      "1.000",
      "us",
      "2380",
      "-1",
      "-1",
      "C"
    ],
    [
      "1997 WQ23",
      "2013-11-19 00:38:00",
      "96148022.94",
      "4.000",
      "us",
      "2380",
      "-1",
      "-1",
      "C"
    ],
    [
      "1997 WQ23",
      "2013-11-19 00:25:00",
      "-124458.2215",
      "0.300",
      "Hz",
      "2380",
      "-1",
      "-1",
      "C"
    ]
  ]
}

Radar Stations

Radar stations codes are indicated by a negative integer (e.g., “-14” for “DSS 14”). Common radar station codes are listed in the table below.

code name
-1 Arecibo
-2 Haystack
-9 Green Bank (GBT)
-13 DSS 13
-14 DSS 14
-25 DSS 25
-38 Evpatoria
-73 EISCAT Tromso UHF (32-m)

If requested via the coords query parameter option, each radar station’s coordinates in the requested radar astrometry will be output under the JSON coords object. By default, these coordinates are output as geodetic (longitude, latitude, and altitude). If the c-coords query parameters is set, the coordinates are output in cylindrical form (longitude, d_xy, and d_z). The following tables detail these fields and their units.

Geodetic Coordinates

field units description
longitude degrees geodetic east longitude
latitude degrees geodetic north latitude
altitude alt_units elevation above the WGS84 reference ellipsoid
alt_units   m=meters, km=kilometers, ft=feet

Cylindrical Coordinates

field units description
longitude degrees geodetic east longitude
d_xy 10-7 au parallax constant perpendicular to Earth’s spin axis
d_z 10-7 au parallax constant along Earth’s spin axis

Sample Data Output

...

"coords" : {
  "-1" : {
    "alt_units" : "m",
    "altitude" : "450.56",
    "latitude" : "18.34420",
    "longitude" : "293.2473",
    "name" : "Arecibo"
  },
  "-13" : {
    "alt_units" : "m",
    "altitude" : "1067.86",
    "latitude" : "35.24720",
    "longitude" : "243.2055",
    "name" : "DSS 13"
  },
  "-14" : {
    "alt_units" : "m",
    "altitude" : "1006.94",
    "latitude" : "35.42590",
    "longitude" : "243.1105",
    "name" : "DSS 14"
  }
},

...

HTTP Response Codes

All errors are returned via appropriate HTTP response codes.

HTTP Code Description Typical Usage
200 OK normal successful result: data returned
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 June)

  • Initial release