Version: 1.1 (2022 February)
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.
GET
https://ssd-api.jpl.nasa.gov/sb_radar.api
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)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) |
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 ) |
{
"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 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.
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 |
field | units | description |
---|---|---|
longitude | degrees | geodetic east longitude |
d_xy | 10-10 au | parallax constant perpendicular to Earth’s spin axis |
d_z | 10-10 au | parallax constant along Earth’s spin axis |
...
"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"
}
},
...
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 |