Sentry API

Version: 1.0 (2016 August)
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.

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.

Data are returned in JSON format. The specific structure used is dependent on the query mode.

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":"1.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":"1.0","source":"NASA/JPL Sentry Data API"},
  "error" : "specified object not found"
}

The following are normal Mode O response JSON payload examples.

{
  "signature" : {"version":"1.0","source":"NASA/JPL Sentry Data API"},
  "energy" : "0.414389180671304",
  "darc" : "14.798 days",
  "ip" : "1.08833e-06",
  "h" : "25.96",
  "nobs" : "75",
  "mass" : "13958716.7495153",
  "v_inf" : "11.1877691509009",
  "first_obs" : "2015-Oct-23.45412",
  "ndop" : "0",
  "pdate" : "2016-01-04 16:27:23",
  "cdate" : "2016-01-04 16:27:23",
  "ps_cum" : "-6.5946536483993",
  "diameter" : "0.022",
  "v_imp" : "15.7885127672673",
  "ndel" : "0",
  "ps_max" : "-6.85",
  "last_obs" : "2015-Nov-07.251926",
  "fullname" : "       (2015 UH52)",
  "ts_max" : "0",
  "n_imp" : "3",
  "nsat" : "0",
  "des" : "2015 UH52"
  },
  "data":[
    {
       "width" : "7.8568e-03",
       "energy" : "4.149e-01",
       "ts" : "0",
       "ip" : "5.148e-07",
       "stretch" : "1.1401e+06",
       "date" : "2075-10-21.11",
       "dist" : "0.563",
       "sigma_lov" : "-0.48184",
       "sigma_imp" : "0.000",
       "ps" : "-6.85"
    },
    {
       "width" : "0.0000e+00",
       "energy" : "4.129e-01",
       "ts" : "0",
       "ip" : "8.093e-08",
       "stretch" : "2.3142e+06",
       "date" : "2090-10-20.84",
       "dist" : "0.450",
       "sigma_lov" : "-1.64065",
       "sigma_imp" : "0.000",
       "ps" : "-7.75"
    },
    {
       "width" : "8.7842e-03",
       "energy" : "4.141e-01",
       "ts" : "0",
       "ip" : "4.926e-07",
       "stretch" : "4.5121e+05",
       "date" : "2101-10-21.28",
       "dist" : "0.133",
       "sigma_lov" : "-1.59426",
       "sigma_imp" : "0.000",
       "ps" : "-7.02"
    }
  ]
}

Second example from a numbered NEA:

{
  "signature" : {"version":"1.0","source":"NASA/JPL Sentry Data API"},
  "summary":{
    "energy" : "7.538e+04",
    "darc" : "24010.3 days",
    "ip" : "1.2e-04",
    "h" : "17.55",
    "nobs" : "523",
    "mass" : "1.956e+12",
    "v_inf" : "14.10",
    "first_obs" : "1950-Feb-22.230140",
    "ndop" : "4",
    "pdate" : "2015-12-07 14:30:02",
    "cdate" : "2015-12-07 14:30:02",
    "ps_cum" : "-1.42",
    "diameter" : "1.3e+00",
    "v_imp" : "17.99",
    "ndel" : "8",
    "ps_max" : "-1.42",
    "last_obs" : "2015-Nov-18.504940",
    "fullname" : " 29075 (1950 DA)",
    "ts_max" : null,
    "n_imp" : "1",
    "nsat" : "0",
    "des" : "29075"
  },
  "data":[
    {
      "width" : "0.001",
      "energy" : "7.538e+04",
      "ts" : null,
      "ip" : "1.2e-04",
      "stretch" : "5.26e+02",
      "date" : "2880-03-16.99",
      "dist" : "0.037",
      "sigma_lov" : "-2.345",
      "sigma_imp" : "0.000",
      "ps" : "-1.42"
    }
  ]
}

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.
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 (Pacific Local) of 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.

Field Units Description
date   Calendar date (UTC) of the potential impact formatted as YYYY-MM-DD.DD (e.g., 2880-03-16.99).
dist rE 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 One-sigma semi-width of the LOV uncertainty region, measured in Earth radii.
sigma_imp   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   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 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.
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 Browser 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":"1.0","source":"NASA/JPL Sentry Data API"},
  "count":3,
  "data":[
    {
      "des":"29075",
      "fullname":"29075 (1950 DA)",
      "range":"2880-2880",
      "n_imp":1,
      "ip":"1.2e-04",
      "v_inf":"14.10",
      "last_obs":"2015-Nov-18.504940",
      "last_obs_jd":"2457345.00494",
      "h":"17.6",
      "diameter":"1.300",
      "ps_cum":"-1.42",
      "ps_max":"-1.42",
      "ts_max":null
    },
    {
      "des":"2010 DG77"
      "fullname":"2010 DG77",
      "range":"2023-2111",
      "n_imp":144,
      "ip":"1.5e-06",
      "v_inf":"2.39",
      "last_obs":"2010-Feb-19.77116",
      "last_obs_jd":"2455247.27116",
      "h":"24.5",
      "diameter":"0.044",
      "ps_cum":"-5.54",
      "ps_max":"-6.23",
      "ts_max":0
    },
    {
      "des":"2015 RN35"
      "fullname":"2015 RN35",
      "range":"2043-2109",
      "n_imp":9,
      "ip":"7.3e-06",
      "v_inf":"5.73",
      "last_obs":"2016-Mar-07.32122",
      "last_obs_jd":"2457454.82122",
      "h":"23.0",
      "diameter":"0.087",
      "ps_cum":"-4.20",
      "ps_max":"-4.35",
      "ts_max":0
    }
  ]
}

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":"1.0","source":"NASA/JPL Sentry Data API"},
  "count" : 0,
  "data" : []
}

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

{
  "signature" : {"version":"1.0","source":"NASA/JPL Sentry Data API"},
  "count" : 5,
  "data" : [
    {
      "width" : "1.6347e-04",
      "energy" : "8.193e-03",
      "ts" : "0",
      "ip" : "9.575e-03",
      "stretch" : "6.8318e+01",
      "date" : "2074-05-03.03",
      "dist" : "0.434",
      "sigma_lov" : "-0.43580",
      "sigma_imp" : "0.000",
      "fullname" : "       (2006 JY26)",
      "id" : "bK06J26Y",
      "ps" : "-3.93",
      "des" : "2006 JY26"
    },
    {
      "width" : "3.5000e-04",
      "energy" : "9.005e-03",
      "ts" : "0",
      "ip" : "6.501e-02",
      "stretch" : "1.1018e+01",
      "date" : "2095-09-05.99",
      "dist" : "0.438",
      "sigma_lov" : "-0.01172",
      "sigma_imp" : "0.000",
      "fullname" : "       (2010 RF12)",
      "id" : "bK10R12F",
      "ps" : "-3.20",
      "des" : "2010 RF12"
    },
    {
      "width" : "3.9936e-04",
      "energy" : "2.308e-03",
      "ts" : "0",
      "ip" : "1.101e-03",
      "stretch" : "2.1950e+02",
      "date" : "2069-05-01.93",
      "dist" : "0.716",
      "sigma_lov" : "1.29274",
      "sigma_imp" : "0.000",
      "fullname" : "       (2014 JR24)",
      "id" : "bK14J24R",
      "ps" : "-5.27",
      "des" : "2014 JR24"
    },
    {
      "width" : "1.6403e-02",
      "energy" : "2.756e-02",
      "ts" : "0",
      "ip" : "1.056e-03",
      "stretch" : "4.7938e+02",
      "date" : "2059-12-14.34",
      "dist" : "0.051",
      "sigma_lov" : "-0.95200",
      "sigma_imp" : "0.000",
      "fullname" : "       (2015 YJ)",
      "id" : "bK15Y00J",
      "ps" : "-4.34",
      "des" : "2015 YJ"
    },
    {
      "width" : "0.000",
      "energy" : "1.448e+02",
      "ts" : null,
      "ip" : "1.4e-03",
      "stretch" : "2.23e+02",
      "date" : "2185-03-29.75",
      "dist" : "0.513",
      "sigma_lov" : "1.298",
      "sigma_imp" : "0.000",
      "fullname" : "410777 (2009 FD)",
      "id" : "a0410777",
      "ps" : "-1.83",
      "des" : "410777"
    }
  ]
}

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":"1.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 a method other than GET or POST
500 Internal Server Error for example, the database is not available at the time of the request

Change Log

Version 1.0 (2016 August)

  • Initial release