Sentry API

Version: 2.0 (2021 July)
change log

This API provides access to results from the CNEOS Sentry system. There are various “modes” used to obtain desired data.

  • O - object-specific details table
  • S - summary table
  • V - VI (virtual impactor) table
  • R - removed-objects table

HTTP Request

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

Example Queries

  • O - get details for the specified Sentry object:
    • https://ssd-api.jpl.nasa.gov/sentry.api?des=99942 (99942 Apophis)
    • https://ssd-api.jpl.nasa.gov/sentry.api?des=2000%20SG344 (2000 SG344)
  • S - get summary data for available Sentry objects:
    • https://ssd-api.jpl.nasa.gov/sentry.api
  • V - get VI data for available Sentry objects with IP>=1e-3:
    • https://ssd-api.jpl.nasa.gov/sentry.api?all=1&ip-min=1e-3
  • R - get data for objects removed from Sentry:
    • https://ssd-api.jpl.nasa.gov/sentry.api?removed=1

Query Parameters

This API supports four query modes.

  • O - obtain details related to a specified Sentry object
  • S - obtain summary data for all available Sentry objects
  • V - obtain data for all available VIs (Virtual Impactors)
  • R - obtain summary data for objects removed from Sentry
Parameter Type Default Allowable Values Function Modes Description
spk int none   selector O select data for the object matching this SPK-ID (e.g., 2029075 )
des string none   selector O select data for the object matching this designation (e.g., 29075 or 2000 SG344) [Note: basename-form may also be used, e.g., a29075 or 2000sg344]
h-max number none [-10:100] filter S,V limit data to those with an absolute magnitude, H (weighted-mean for mode-S) less than or equal to this value
ps-min integer none [-20:20] filter S,V limit data to those with a (weighted-mean for mode-S) Palermo scale (PS) greater than or equal to this value
ip-min number none [1 - 1e-10] filter S,V limit data to those with a (weighted-mean for mode-S) impact-probability (IP) greater than or equal to this value
days int none ABS(days) > 6 filter S,V number of days since last observation: limit data to those objects that have been observed within the specified number of days (if the number is negative, limit data to those which have not been observed with the specified number of days)
all boolean false [1,Y,true] selector V request the complete VI data set
removed boolean false [1,Y,true] selector R request the list of removed objects

The presence of an object selector query parameter (des or spk) implies mode O, while the presence of query parameter removed implies mode R and query parameter all implies mode V. If none of these parameters are specified, mode S is assumed.

Using a combination of query parameters associated with more than one mode results in an error. For example, if an object selector parameter is specified and the days parameter is also specified, an error will be returned.

For mode O, use only one of the available object selector parameters. If more than one is specified (e.g., both des and spk), an error will be returned.

The new version of the Sentry system, Sentry-II, uses the impact pseudo-observation method to find and characterize virtual impactors. The database may still contain ancillary data or special cases processed with the line-of-variations (LOV) or Monte Carlo (MC) methods.

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. The specific structure used is dependent on the query mode.

Analysis Method

Version 2.0

Starting with version 2.0, Sentry no longer relies on the line-of-variations (LOV) method to find virtual impactors. Instead, it implements the impact pseudo-observation (IOBS) method. The default data returned by the API is computed with this technique, although results from special MC or LOV runs may also be present.

Version 1.1

With version 1.1, Sentry allows for MC analysis method in addition to the default LOV analysis method. A new field method is output under the Mode O summary section and also under the Mode V data. Note that there are fields specific to each method.

Monte Carlo (MC) specific fields: sigma_mc.

Line-of-Variations (LOV) specific fields: dist, width, sigma_imp, sigma_lov, and stretch.

In the data output for Modes O and V, only fields specific to the method with be output. For example, if method is “MC”, the dist, width, sigma_imp, sigma_lov, and stretch fields will NOT be output. See the examples below for Mode O and Mode V.

Mode O

Object details data are split into two sections. The first section (summary) contains the summary data showing weighted mean values for selected parameters. The second section (data) contains a record for each virtual impactor (VI).

If the specified object has been moved to Sentry’s removed table, a 200 response is returned with additional information in the JSON payload (removed keyword contains the date/time of removal). This can be used to distinguish from other abnormal responses and provide a more meaningful response to the end user.

{
  "signature" : {"version":"2.0","source":"NASA/JPL Sentry Data API"},
  "error" : "specified object removed",
  "removed" : "2016-04-01 12:00:00"
}

If the object was never in Sentry, the following is returned.

{
  "signature" : {"version":"2.0","source":"NASA/JPL Sentry Data API"},
  "error" : "specified object not found"
}

The following are normal Mode O response JSON payload examples.

First example from an unnumbered NEA (method “IOBS”):

{
  "signature" : {"version":"2.0","source":"NASA/JPL Sentry Data API"},
  "summary" : {
    "cdate" : "1969-12-31 16:00:00",
    "darc" : "19.185 days",
    "des" : "2019 BO",
    "diameter" : "0.0081",
    "energy" : "1.480e-02",
    "first_obs" : "2019-01-17",
    "fullname" : "(2019 BO)",
    "h" : "28.12",
    "ip" : "8.61883e-06",
    "last_obs" : "2019-02-05",
    "mass" : "7.02e+05",
    "method" : "IOBS",
    "n_imp" : "9",
    "ndel" : "0",
    "ndop" : "0",
    "nobs" : "21",
    "nsat" : "0",
    "pdate" : "2020-09-16 14:55:29",
    "ps_cum" : "-6.75",
    "ps_max" : "-7.22",
    "ts_max" : "0",
    "v_imp" : "13.31",
    "v_inf" : "7.28"
  }
  "data" : [
    {
      "date" : "2055-01-16.13",
      "energy" : "1.484e-02",
      "ip" : "5.584e-07",
      "ps" : "-7.74",
      "sigma_vi" : "1.6872",
      "ts" : "0"
    },
    {
      "date" : "2067-01-16.23",
      "energy" : "1.481e-02",
      "ip" : "1.018e-06",
      "ps" : "-7.61",
      "sigma_vi" : "2.4395",
      "ts" : "0"
    },
    ...
  ]
}

Mode O summary Fields

The following table describes fields output in the summary section of a Mode O payload.

Field Units Description
des   Primary designation of the object.
method   Analysis method used: IOBS = Impact pseudo-observation, LOV = Line-of-Variations, MC = Monte Carlo.
fullname   Full name/designation of the object.
ps_cum   The cumulative hazard rating according to the Palermo technical impact hazard scale, based on the tabulated impact date, impact probability and impact energy.
ps_max   Maximum hazard rating according to the Palermo technical impact hazard scale
ts_max   Maximum detected hazard rating according to the Torino impact hazard scale, based on the tabulated impact probability and impact energy. The Torino Scale is defined only for potential impacts less than 100 years in the future.
ip   The cumulative probability that the tabulated impact will occur. The probability computation is complex and depends on a number of assumptions that are difficult to verify. For these reasons the stated probability can easily be inaccurate by a factor of a few, and occasionally by a factor of ten or more.
n_imp   Total number of potential impacts resulting from this analysis
energy Mt The kinetic energy at impact: 0.5 × mass × v_imp2, measured in Megatons of TNT.
h   Absolute Magnitude, a measure of the intrinsic brightness of the object.
diameter km This is an estimate based on the absolute magnitude, usually assuming a uniform spherical body with visual albedo of 0.154 (in accordance with the Palermo Scale) but sometimes using actual measured values if these are available. Since the albedo is rarely measured, the diameter estimate should be considered only approximate, but in most cases will be accurate to within a factor of two.
mass kg This estimate assumes a uniform spherical body with the computed diameter and a mass density of 2.6 g/cm3. The mass estimate is somewhat more rough than the diameter estimate, but generally will be accurate to within a factor of three.
v_inf km/s Relative velocity at atmospheric entry neglecting the acceleration caused by the Earth’s gravity field, often called the hyperbolic excess velocity.
v_imp km/s Velocity at atmospheric entry.
pdate   Date and time (UTC) used in the Palermo scale computation.
cdate   Date and time (Pacific Local) of the impact analysis computation.
first_obs   Date and time (UTC) of the first observation used in the analysis.
last_obs   Date and time (UTC) of the last observation used in the analysis.
darc d Number of days spanned by the observations used the the analysis.
nobs   Total number of observations used in the analysis.
ndel   Number of radar delay (range) observations used in the analysis.
ndop   Number of radar Doppler observations used in the analysis.
nsat   Number of optical satellite observations used in the analysis.

The above fields energy, h, diameter, mass, v_inf, and v_imp are mean values weighted by impact probability.

Mode O data Fields

The following table describes fields output in the summary section of a Mode O payload. Fields with a Method indicated are only output for the corresponding method.

Field Units Method Description
date     Calendar date (UTC) of the potential impact formatted as YYYY-MM-DD.DD (e.g., 2880-03-16.99).
dist rE LOV Minimum distance on the target plane (scaled b-plane) from the LOV to the geocenter, measured in Earth radii. For these purposes the radius of the Earth, 6420 km, includes some allowance for the thickness of the atmosphere.
width rE LOV One-sigma semi-width of the LOV uncertainty region, measured in Earth radii.
sigma_imp   LOV Lateral distance in sigmas from the LOV to the Earth’s atmosphere. Zero indicates that the LOV intersects the Earth. It is computed from (dist - 1)/width.
sigma_lov   LOV Coordinate along the Line Of Variations (LOV). This value is a measure of how well the impacting orbit fits the available observations. Zero indicates the best-fitting, central (nominal) orbit and the further from zero, the less likely the event: Roughly 99% of all the uncertainty region lies between -3 and +3. Sentry explores out to Sigma LOV = +/-5.
stretch rE LOV Stretching is the semimajor axis of the local linear uncertainty region. It describes how fast one moves across the target plane as Sigma LOV (sigma_lov) changes, and is measured in Earth radii per sigma. The local probability density varies inversely with the stretching, and thus larger stretching values will generally lead to lower impact probabilities.
sigma_mc   MC A metric that quantifies how well the impacting orbit fits the observations. Zero indicates the best-fitting, central (nominal) orbit and the further from zero, the less likely the event: For an orbit defined by six orbital parameters, roughly 83% of the uncertainty region is within 3-sigma.
sigma_vi   IOBS A metric that quantifies how well the nominal impacting orbit computing with the extended orbit-determination filter fits the observations. Zero indicates the best-fitting, central (nominal) orbit and the further from zero, the less likely the event: For an orbit defined by six orbital parameters, roughly 83% of the uncertainty region is within 3-sigma.
ip     Probability that the tabulated impact will occur. The probability computation is complex and depends on a number of assumptions that are difficult to verify. For these reasons the stated probability can easily be inaccurate by a factor of a few, and occasionally by a factor of ten or more.
energy Mt   Kinetic energy at impact, based upon the computed absolute magnitude and impact velocity for the particular case, and computed in accordance with the guidelines stated for the Palermo Technical Scale. Uncertainty in this value is dominated by mass uncertainty and the stated value will generally be good to within a factor of three.
ps     Hazard rating according to the Palermo technical impact hazard scale.
ts     Hazard rating according to the Torino impact hazard scale, based on the tabulated impact probability and impact energy. The Torino Scale is defined only for potential impacts less than 100 years in the future.

Mode S

Each field is a character string except for the integer value for the number of impactors (n_imp). The des field can be used to assemble an appropriate URL to the SBDB Lookup page, for example. The id field should be used for sorting by object. Several values are mean-values weighted by impact probability: h, diameter, v_inf, and ps_cum.

{
  "signature" : {"version":"2.0","source":"NASA/JPL Sentry Data API"},
  "count" : 3,
  "data" : [
    {
      "des" : "1979 XB",
      "diameter" : "0.66",
      "fullname" : "(1979 XB)",
      "h" : "18.56",
      "id" : "bJ79X00B",
      "ip" : "8.89646e-07",
      "last_obs" : "1979-12-15",
      "last_obs_jd" : "2444222.5",
      "n_imp" : "5",
      "ps_cum" : "-2.75",
      "ps_max" : "-3.12",
      "range" : "2056-2113",
      "ts_max" : "0",
      "v_inf" : "23.7204343975019"
    },
    {
      "des" : "1994 GK",
      "diameter" : "0.048",
      "fullname" : "(1994 GK)",
      "h" : "24.24",
      "id" : "bJ94G00K",
      "ip" : "6.9957638e-05",
      "last_obs" : "1994-04-10",
      "last_obs_jd" : "2449452.5",
      "n_imp" : "8",
      "ps_cum" : "-3.61",
      "ps_max" : "-3.62",
      "range" : "2050-2067",
      "ts_max" : "0",
      "v_inf" : "14.8709547057606"
    },
    {
      "des" : "2000 SB45",
      "diameter" : "0.046",
      "fullname" : "(2000 SB45)",
      "h" : "24.34",
      "id" : "bK00S45B",
      "ip" : "0.00015927734411",
      "last_obs" : "2000-09-29",
      "last_obs_jd" : "2451816.5",
      "n_imp" : "227",
      "ps_cum" : "-3.75",
      "ps_max" : "-4.22",
      "range" : "2068-2118",
      "ts_max" : "0",
      "v_inf" : "7.53074757034446"
    },
  ]
}

Mode V

Data are similar to the second part of the Mode O output. If specified constraints are too limiting, it’s possible to have a result with no matching objects.

{
  "signature" : {"version":"2.0","source":"NASA/JPL Sentry Data API"},
  "count" : 0,
  "data" : []
}

Here’s an example of a limited (filtered) result.

{
   "signature" : {"version":"2.0","source":"NASA/JPL Sentry Data API"},
   "count" : 4,
   "data" : [
      {
         "date" : "2022-05-06.34",
         "des" : "2009 JF1",
         "energy" : "2.266e-01",
         "fullname" : "(2009 JF1)",
         "id" : "bK09J01F",
         "ip" : "2.593e-04",
         "method" : "IOBS",
         "ps" : "-2.88",
         "sigma_vi" : "0.5915",
         "ts" : "0"
      },
      {
         "date" : "2075-11-16.14",
         "des" : "2014 WA201",
         "energy" : "1.308e-01",
         "fullname" : "(2014 WA201)",
         "id" : "bK14WK1A",
         "ip" : "1.943e-04",
         "method" : "IOBS",
         "ps" : "-4.64",
         "sigma_vi" : "1.0815",
         "ts" : "0"
      },
      {
         "date" : "2048-01-11.42",
         "des" : "2011 AM37",
         "energy" : "1.224e-03",
         "fullname" : "(2011 AM37)",
         "id" : "bK11A37M",
         "ip" : "7.771e-04",
         "method" : "IOBS",
         "ps" : "-5.36",
         "sigma_vi" : "0.7069",
         "ts" : "0"
      },
      {
         "date" : "2063-01-10.54",
         "des" : "2011 AM37",
         "energy" : "1.228e-03",
         "fullname" : "(2011 AM37)",
         "id" : "bK11A37M",
         "ip" : "2.130e-04",
         "method" : "IOBS",
         "ps" : "-6.11",
         "sigma_vi" : "2.0630",
         "ts" : "0"
      }
   ]
}

Mode R

For removed-objects queries (mode R), there should always be data returned. Currently, there is no provision to limit the number of results so the entire data-set is returned. Note that the designation returned (des) is that designation associated with the object at the time of removal. An object removed many months prior could have a different primary provisional designation or even be numbered. The removed field indicates the date/time (UTC) when the object was removed.

Objects are removed when all previous potential impacts are eliminated. This is typically the result of an increase in the available set of observations.

The following is an example showing the first three records:

{
  "signature" : {"version":"2.0","source":"NASA/JPL Sentry Data API"},
  "count" : 3,
  "data" : [
    {
      "des" : "2015 VD2",
      "removed" : "2015-12-14 16:06"
    },
    {
      "des" : "2011 HP4",
      "removed" : "2015-12-14 16:05"
    },
    {
      "des" : "2015 XX128",
      "removed" : "2015-12-08 17:00"
    }
  ]
}

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 (including requested for objects not available in Mode O)
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 for example, 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 (2016 August)

  • Initial release

Version 1.1 (2017 September)

  • Added fields to support output of results from Monte Carlo analysis method in addition to the line-of-variations (LOV) anaysis method.

Version 2.0 (2021 July)

  • Implemented the impact pseudo-observation (IOBS) method to detect and characterize virtual impactors. The IOBS method replaces the LOV method as the default impact monitoring algorithm.