Scout Data API

Version: 1.3 (2021 September)
change log

This API provides access to near-realtime results from the CNEOS Scout system. Various query modes provide access to available subsets of data. See the examples and query parameters below for details.

HTTP Request

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

Example Summary Query

get all available summary data:
- https://ssd-api.jpl.nasa.gov/scout.api

Example Object Detail Queries

Note that the NEOCP object tdes used in the following examples is not guaranteed to still exist in the database.

get summary data for a specific NEOCP object (e.g., “P10vY9r”):
- https://ssd-api.jpl.nasa.gov/scout.api?tdes=P10vY9r
get orbital-element plot files and summary data for a specific object:
- https://ssd-api.jpl.nasa.gov/scout.api?tdes=P10vY9r&plot=el
get close-approach and orbital-element plot files in addition to summary data for a specific object:
- https://ssd-api.jpl.nasa.gov/scout.api?tdes=P10vY9r&plot=ca:el
get sampled orbits and related parameters for a specific object:
- https://ssd-api.jpl.nasa.gov/scout.api?tdes=P10vY9r&orbits=1

Example Ephemeris Queries

Note that the NEOCP object tdes used in the following examples is not likely to still exist in the database. You should use a current object tdes.

get ephemeris data for a specific NEOCP object at the current time:
- https://ssd-api.jpl.nasa.gov/scout.api?tdes=P10vY9r&eph-start
- https://ssd-api.jpl.nasa.gov/scout.api?tdes=P10vY9r&eph-start=now
get ephemeris data for a specific NEOCP object at the specified time:
- https://ssd-api.jpl.nasa.gov/scout.api?tdes=P10vY9r&eph-start=2016-09-24T12:00:00
get ephemeris data for a specific NEOCP object over a range of times at 2-hour intervals:
- https://ssd-api.jpl.nasa.gov/scout.api?tdes=P10vY9r&eph-start=2016-09-25T18:00:00&eph-stop=2016-09-26T06:00:00&eph-step=2h

Note that the ephemeris time(s) requested must be within 30 days of the current date.

Example Ephemeris Queries with Field-of-View

These examples result in a score indicating the likelihood of the NEOCP object being detected in the specified field-of-view (FoV) and optionally also the specified limiting V-magnitude. Note that the FoV requires at least the diameter be specified.

get ephemeris data for a specific NEOCP object at the current time given a FoV diameter of 5 arc-minutes at the nominal ephemeris center:
- https://ssd-api.jpl.nasa.gov/scout.api?tdes=P10vY9r&eph-start&fov-diam=5
get ephemeris data for a specific NEOCP object at the current time given a FoV diameter of 5 arc-minutes at the nominal ephemeris center and limiting V-magnitude of 23.1:
- https://ssd-api.jpl.nasa.gov/scout.api?tdes=P10vY9r&eph-start&fov-diam=5&fov-vmag=23.1

Query Parameters

Parameter	Type	Default	Allowable Values/Format	Modes	Description
tdes	int	none		O,E	select data for the NEOCP object matching this temporary designation (e.g., `P10uUSw` )
plot	string	none	“el”, “ca”, “sr”, “el:ca”, “ca:el:sr” or any similar combination delimited by `:` where duplicates are ignored	O	get plot files for the specified NEOCP object of the selected type (`el`=elements, `ca`=close-approach, `sr`=systematic-ranging) [results are Base64-encoded image data]
file	string	none	“list”, “mpc”	O	get the list of available data files (when `file=list`) or get the requested data file for the specified NEOCP object; currently, only “mpc” file is available; see below for more information
orbits	boolean	false	true, false, 1, 0	O,E	get sampled orbits data for the specified NEOCP object
n-orbits	positive number	1000	[1:1000]	O,E	limit the number of sampled orbits to this value
eph-start	string	“now”	`YYYY`-`MM`-`DD` `YYYY`-`MM`-`DD` `hh`:`mm`:`ss` `YYYY`-`MM`-`DD`_`hh`:`mm`:`ss` `YYYY`-`MM`-`DD`T`hh`:`mm`:`ss` “now”	E	get the ephemeris for the specified NEOCP object at this time UTC
eph-stop	string	none	`YYYY`-`MM`-`DD` `YYYY`-`MM`-`DD` `hh`:`mm`:`ss` `YYYY`-`MM`-`DD`_`hh`:`mm`:`ss` `YYYY`-`MM`-`DD`T`hh`:`mm`:`ss`	E	set the ephemeris stop-time (if specified, requires `eph-start` and must be later than `eph-start`)
eph-step	string	see description	`#`d, `#`h, `#`m (where `#` is a positive definite integer)	E	set the ephemeris step-size (if specified, requires both `eph-start` and `eph-stop`; if not specified, set to the span)
obs-code	string	“500”	valid MPC code	E	get the ephemeris for the specified NEOCP object relative to the specified MPC observatory code
fov-diam	positive number	none	(0:1800]	E	specify the size (diameter) of the field-of-view in arc-minutes
fov-ra	string	median R.A.	deg `hh`:`mm`:`ss.s` `hh` `mm` `ss.s` [0:360) degrees [0:24) hours	E	specify the field-of-view center (R.A. component) [requires `fov-diam` and `fov-dec`; invalid if `eph-stop` is set]
fov-dec	string	median Dec.	+/-deg `dd`-`mm`-`ss` `dd` `mm` `ss` (absolute value must be less than 90 degrees)	E	specify the field-of-view center (Dec. component) [requires `fov-diam` and `fov-ra`; invalid if `eph-stop` is set]
fov-vmag	positive number	none	[0:40]	E	filter ephemeris results to those with V-magnitude of this value or brighter [requires `fov-diam`]
ranges	boolean	false	true, false, 1, 0	E	get topocentric (geocentric if `obs-code` is 500) and heliocentric ranges

NOTES:

Mixing query parameters associated with different modes is not allowed. For example, combining “plot=el” with “eph-start=now” results in an error response.
Note that mode S is selected by not specifying any parameter.
Both mode O and mode E require tdes to be specified.

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

Successful query requests result in a JSON-format data payload. The specific content depends on the query mode. See below.

Mode `S` (Summary Data)

This payload contains the number of records available (“count”). If “count” is greater than zero, the payload also contains a “data” record which is an array of available data. Each Scout record is packaged as a key/value set with the following keys (currently, key names correspond to the database table field names).

objectName
nObs
arc
rmsN
H
rating
moid
caDist
vInf
phaScore
neoScore
geocentricScore
ieoScore
tisserandScore
lastRun
ra
dec
elong
rate
Vmag
unc
uncP1

Mode `O` (Object Data)

This payload contains the record for the specified object. If the specified object does not match any record, an error is returned in the JSON payload.

{ "error":"specified object does not exist" }

The object data payload contains all the fields provided in the summary mode S as well as optional additional fields for data files, plot files and/or sampled orbital data as described below.

data files

Data contain the requested data file, text-format. These files are designed for display using a fixed-format font. Currently, only the MPC-format observation data file is available.

file=mpc provides the MPC-format observation data file

To get the list of available data files, use file=list. Sample output showing results from file=list for a mode O query is shown below. If the requested file is not available, the size will be set to null. Note that the example shows only the file section of the output (see full mode O sample output below for a complete example).

"file": {
  "mpc":{"size":486,"name":"Observation File (MPC-format)"},
}

plot files

Data contain binary PNG-format plot files, Base64-encoded.

plot=el provides orbital-element plots
- qr_e_fig
- qr_in_fig
- qr_H_fig
- H_hist_fig
plot=ca provides close-approach plots
- moid_hist_fig
- ca_dist_cdf_fig †
- tca_hist_fig †
- ca_dist_hist_fig †
plot=sr provides systematic-ranging plots
- rms_sysran_fig
- H_sysran_fig

† Note that these close-approach plots are only available for objects which come within 0.5 LD (lunar distance). When not available, these plots will be null.

sampled orbits data

Data contain available sampled orbits orbital elements and related parameters. The format of these data is shown under Sample Output Data below.

Mode `E` (Ephemeris Data)

This payload contains the record for the specified object as well as the requested ephemeris output. Ephemeris output at each requested time provides data in three groups with corresponding fields as detailed below.

Note that the API limits the number of ephemeris output records to 500. Specify appropriate values for eph-start, eph-stop, and eph-step to ensure this limit is not exceeded.

summary ephemeris information

count (the number of ephemeris output times, typically 1)
orbit-count (the number of sampled orbits ephemerides at each time, typically 1000)
data-fields (a list of field names corresponding to each ephemeris record)

nominal ephemeris and summary information

time (YYYY-MM-DD hh:mm:ss) UTC
sun-flag (null, a, n, c, *)
1-sigma plane-of-sky uncertainty sigma-pos (arc-minutes)
median results
- RA/Dec (J2000, degrees)
- dRA/dDec (arc-seconds/minute) [ dRA accounts for cos(Dec) factor ]
- POS rate (arc-seconds/minute) [ computed from median dRA/dDec values ]
- PA (degrees) [ computed from median dRA/dDec values ]
- V-mag
- solar elongation (degrees)
- lunar separation (degrees) [ angular distance between the moon and object ]
- elevation (degrees) [ relative to the local horizon - not present for geocentric obs-code ]
- topocentric range (au) [ geocentric if obs-code is 500, output only if the ranges parameter is true ]
- heliocentric range (au) [ output only if the ranges parameter is true ]
minimum/maximum results
- RA/Dec (J2000, degrees)
- dRA/dDec (arc-seconds/minute) [ dRA accounts for cos(Dec) factor ]
- POS rate (arc-seconds/minute)
- PA (degrees)
- V-mag
- solar elongation (degrees)
- lunar separation (degrees) [ angular distance between the moon and object ]
- elevation (degrees) [ relative to the local horizon - not present for geocentric obs-code ]
- topocentric range (au) [ geocentric if obs-code is 500, output only if the ranges parameter is true ]
- heliocentric range (au) [ output only if the ranges parameter is true ]
1-sigma minimum/maximum results
- RA/Dec (J2000, degrees)
- V-mag

The sun-flag field is not output for geocentric ephemerides (i.e., when obs-code is null or “500”). Possible values and their meanings are as follows.

null - the sun is below the horizon (night time)
a - the sun is in astronomical twilight
n - the sun is in nautical twilight
c - the sun is in civil twilight
* - the sun is above the horizon (daylight)

ephemeris for each sampled orbit

RA - right ascension (J2000, degrees)
Dec - declination (J2000, degrees)
POS rate (arc-seconds/minute)
PA (degrees)
V-mag
solar elongation (degrees)
lunar separation (degrees)
NEO flag (1=NEO orbit, 0 otherwise)
PHA flag (1=PHA orbit, 0 otherwise)
geo flag (1=geocentric orbit, 0 otherwise)
impactor flag (1=virtual impactor, 0 otherwise)
elevation (degrees) [ relative to the local horizon - not present for geocentric obs-code ]
topocentric range (au) [ geocentric if obs-code is 500, output only if the ranges parameter is true ]
heliocentric range (au) [ output only if the ranges parameter is true ]
sampled orbit index (output only if the orbits parameter is true)

field-of-view results

FoV center (RA/Dec J2000)
FoV diameter (arc-minutes)
V-mag limit (mag)
Score (likelihood of the object being on the FoV considering the limiting magnitude)

Sample Data Output

Mode `S`

{
  "signature":{"version":"1.2","source":"NASA/JPL Scout API"},
  "count":"3","data":[
  {
    "objectName":"XGB1CE8",
    "lastRun":"2016-04-25 20:05:00","uncP1":"0.1","neoScore":"100","rating":"0",
    "rate":"0.3","unc":"0.1","phaScore":"0","ra":"12:29","elong":"147",
    "nObs":"18","arc":"25.47","tisserandScore":"0","caDist":"0.13",
    "vInf":"22.1","H":"29.2","rmsN":"1.06","ieoScore":"0","dec":"-11",
    "geocentricScore":"0","moid":"0.0003","Vmag":"29.2
  },
  {
    "objectName":"XFAC29D",
    "lastRun":"2016-04-25 20:05:00","uncP1":"0.6","neoScore":"100","rating":"0",
    "rate":"0.8","unc":"0.6","phaScore":"0","ra":"01:25","elong":"20",
    "nObs":"15","arc":"8.63","tisserandScore":"0","caDist":"1.59",
    "vInf":"21.0","H":"28.2","rmsN":"0.55","ieoScore":"0","dec":"+11",
    "geocentricScore":"0","moid":"0.0020","Vmag":"32.5"
  },
  {
    "objectName":"P10v2Pz",
    "lastRun":"2016-04-30 15:02:00","uncP1":"667.5","neoScore":"100","rating":"0",
    "rate":"39.2","unc":"382.5","phaScore":"0","ra":"16:59","elong":"139",
    "nObs":"4","arc":"0.91","tisserandScore":"65","caDist":"11.30",
    "vInf":"14.9","H":"26.593450","rmsN":"0.60","ieoScore":"0","dec":"+08",
    "geocentricScore":"0","moid":"0.0235","Vmag":"20.7"
  }
]}

Mode `O`

{
  "signature":{"version":"1.2","source":"NASA/JPL Scout API"},
  "objectName":"YCB34A9",
  "nObs":"5","arc":"0.77","rmsN":"0.46","H":"26.6",
  "rating":"0","moid":"0.02","caDist":"9.8","vInf":"10.3",
  "phaScore":"0","neoScore":"100","neo1kmScore":"0",
  "geocentricScore":"0","ieoScore":"0","tisserandScore":"56",
  "lastRun":"2017-02-06 11:29","unc":"5.8","uncP1":"93",
  "tEphem":"2017-02-06 16:45",
  "ra":"09:33","dec":"+21","elong":"173","rate":"26.9","Vmag":"19.4",
}

with `file=list`

{
  "signature":{"version":"1.2","source":"NASA/JPL Scout API"},
  "objectName":"YCB34A9",
  "nObs":"5","arc":"0.77","rmsN":"0.46","H":"26.6",
  "rating":"0","moid":"0.02","caDist":"9.8","vInf":"10.3",
  "phaScore":"0","neoScore":"100","neo1kmScore":"0",
  "geocentricScore":"0","ieoScore":"0","tisserandScore":"56",
  "lastRun":"2017-02-06 11:29","unc":"5.8","uncP1":"93",
  "tEphem":"2017-02-06 16:45",
  "ra":"09:33","dec":"+21","elong":"173","rate":"26.9","Vmag":"19.4",
  "file":{"size":"486","mpc":{"name":"Observation File (MPC-format)"}}

}

with `orbits=1`

Note that only the first and last ephemeris data records are shown with ... indicating the remaining records. Although there are usually 1000 sampled orbit records, it is possible to have fewer and thus it may be prudent to check the count field.

{
  "signature":{"version":"1.2","source":"NASA/JPL Scout API"},
  "objectName":"YCB34A9",
  "nObs":"5","arc":"0.77","rmsN":"0.46","H":"26.6",
  "rating":"0","moid":"0.02","caDist":"9.8","vInf":"10.3",
  "phaScore":"0","neoScore":"100","neo1kmScore":"0",
  "geocentricScore":"0","ieoScore":"0","tisserandScore":"56",
  "lastRun":"2017-02-06 11:29","unc":"5.8","uncP1":"93",
  "tEphem":"2017-02-06 16:45",
  "ra":"09:33","dec":"+21","elong":"173","rate":"26.9","Vmag":"19.4",
  "orbits":{
    "count":"1000",
    "fields":["idx","epoch","ec","qr","tp","om","w","inc","H","dca","tca","moid","vinf","geoEcc","impFlag"],
    "data":[
      [
        0,
        "2457581.871499164",
        "3.357123709445450E-01",
        "9.083681207232809E-01",
        "2457636.871738402",
        "1.1141193497296813E+02",
        "2.4446138666195648E+02",
        "1.6610875455065550E+01",
        "24.694617",
        null,
        null,
        "0.321364995E-01",
        null,
        1.000000000E+99,
        0
      ],

      ...

      [
        999,
        "2457581.871499164",
        "3.375147127108826E-01",
        "9.080673804565712E-01",
        "2457636.795311817",
        "1.1141510927907412E+02",
        "2.4442420799954962E+02",
        "1.6674246367840780E+01",
        "24.685584",
        null,
        null,
        "0.322590268E-01",
        null,
        1.000000000E+99,
        0
      ]
    ]
  }
}

Mode `E`

{
  "signature":{"version":"1.2","source":"NASA/JPL Scout API"},
  "object":{<OBJECT_DATA>},
  "data-fields":["ra","dec","rate","pa","vmag","elong","moon","neo","pha","geo","imp","el"],
  "orbit-count":"1000",
  "count":"1",
  "eph":[{
    "time":"2018-05-18 22:32:24",
    "sun-flag":"*",
    "median":{
      "ra" : "308.3967895",
      "dec" : "14.1489307",
      "dra" : "4.32",
      "ddec" : "0.26",
      "rate" : "4.33",
      "pa" : "86.5",
      "vmag" : "23.8",
      "elong" : "99",
      "moon" : "134",
      "el" : "-10.9"
    },
    "limits":{
      "ra" : {"min" : "219.8109861","max" : "195.9403700"},
      "dec" : {"min" : "-20.6172540","max" : "45.4457017"},
      "dra" : {"min" : "-2.25","max" : "858.63"},
      "ddec" : {"min" : "-12.00","max" : "164.01"},
      "rate" : {"min" : "0.24","max" : "874.16"},
      "pa" : {"min" : "16.2","max" : "344.7"},
      "vmag" : {"min" : "17.0","max" : "47.4"},
      "elong" : {"min" : "6","max" : "171"},
      "moon" : {"min" : "2","max" : "154"},
      "el" : {"min" : "-81.3","max" : "83.2"}
    },
    "sigma-limits":{
      "ra" : {"min" : "253.4269975","max" : "45.2109508"},
      "dec" : {"min" : "-5.6022615","max" : "25.3189863"},
      "vmag" : {"min" : "21.9","max" : "34.4"}
    },
    "sigma-pos":"6100",
    "data":[
      ["0.5591806","26.3213936","10.42","100.2","25.1","51","94",1,0,0,0,"36.4"],
      ["0.8175939","27.5356781","10.42","96.7","25.1","50","94",1,0,0,0,"36.7"],
      ["1.0689140","27.3895943","10.14","100.3","25.1","50","94",1,0,0,0,"36.9"],
          ...
      ["359.6022557","28.1918181","10.99","97.1","24.9","51","94",1,0,0,0,"35.7"],
      ["359.8036327","27.4370778","10.96","97.4","24.9","51","95",1,0,0,0,"35.8"],
      ["359.8258285","28.0312061","10.61","96.4","25.0","51","94",1,0,0,0,"35.9"]
    ]
  }]
}

NOTES:

The special content <OBJECT_DATA> represents the object data output (see Mode O example above).
The "sun-flag": object is not output for geocentric ephemerides.
When no field-of-view parameters are set, the "fov": object will not be output.

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: may contain an error message if a specified `tdes` was not found
400	Bad Request	the request contained invalid keywords and/or content (details returned in the JSON payload)
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.3 (2021 September)

Added new “ranges” query parameter to request topocentric (or geocentric) and heliocentric ranges

Version 1.2 (2017 February)

Added new “file” query parameter.
Fixed bug in ephemeris flag output fields: neo,pha,geo,imp

Version 1.1 (2017 January)

Changed the output field name for declination from “de” to “dec” to be more consistent with the use of “dec” everywhere else in the API.

Version 1.0 (2016 August)

Initial release