Scout Data API

Version: 1.2 (2017 February)
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-DDThh: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-DDThh: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
(-180:360) degrees
(-12: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]

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 “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. 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.

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)
    • PA (degrees)
    • V-mag
    • elevation (degrees) [ relative to the local horizon - not present for geocentric obs-code ]
  • 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
    • elevation (degrees) [ relative to the local horizon - not present for geocentric obs-code ]
  • 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)
  • 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)
  • sampled orbit index (output only if the orbits parameter is true)
  • elevation (degrees) [ relative to the local horizon - not present for geocentric obs-code ]

field-of-view results

  • FoV center (RA/Dec J2000)
  • FoV diameter (arc-seconds)
  • 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"],
    "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
      ],

      ...

      [
        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
      ]
    ]
  }
}

Mode E

{
  "signature":{"version":"1.2","source":"NASA/JPL Scout API"},
  "object":{<OBJECT_DATA>},
  "data-fields":["ra","dec","rate","pa","vmag","elong","neo","pha","geo","imp"],
  "orbit-count":"1000",
  "count":"1",
  "eph":[{
    "time":"2016-05-03 16:19:09",
    "sun-flag":null,
    "median":{
      "ra":"250.21769",
      "dec":"-2.02338",
      "dra":"-0.281",
      "ddec":"-0.1145",
      "rate":"2.582",
      "pa":"265.5",
      "vmag":"21.4",
    },
    "limits":{
      "ra":{"min":"250.2139","max":"252.5191"},
      "dec":{"min":"-2.0267","max":"-0.9409"},
      "dra":{"min":"-0.53","max":"96.58"},
      "ddec":{"min":"-350.27","max":"-0.08"},
      "rate":{"min":"0.64","max":"92.36"},
      "pa":{"min":"67.6","max":"271.8"},
      "vmag":{"min":"18.5","max":"21.5"}
    },
    "sigma-limits":{
      "ra":{"min":"250.2157","max":"250.2259"},
      "dec":{"min":"-2.0245","max":"-2.0201"},
      "vmag":{"min":"21.4","max":"21.4"}
    },
    "sigma-pos":"0.3",
    "fov":{"diam":"300","ra":"250.2177","dec":"-2.0234","vmag":null,"score":"96"},
    "data":[
      ["250.2139","-2.0234","2.61","265.8","21.4","+148.0",0,0,0,0],
      ["250.2139","-2.0241","2.61","265.7","21.4","+148.0",0,0,0,0],
      ["250.2139","-2.0234","2.62","265.8","21.4","+148.0",0,0,0,0],
          ...
      ["250.86866","-1.7541"," 4.29","82.3","20.9","+147.0",0,0,0,0],
      ["251.17311","-1.5861","14.52","71.3","19.9","+147.0",0,0,0,0],
      ["252.51906","-0.9409","92.36","67.6","18.5","+146.0",0,0,0,0]
    ]
  }]
}

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 or used a request-method other than GET or POST (details returned in the JSON payload)
405 Method Not Allowed the request used a method other than GET or POST
500 Internal Server Error the database is not available at the time of the request

Change Log

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