NHATS API

Version: 1.3 (2019 September)
change log

The NHATS API provides a method of requesting data from the NHATS-related tables in the SBDB. These data will primarily support the CNEOS “Accessible NEAs” web-page. Please see the NHATS web-page for details about NHATS.

HTTP Request

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

Example Queries

• get summary data for available NHATS objects using various constraints:
  • https://ssd-api.jpl.nasa.gov/nhats.api (unconstrained)
  • https://ssd-api.jpl.nasa.gov/nhats.api?dv=6&dur=360&stay=8&launch=2020-2045&h=26&occ=7 (web-page “standard” constraints)
• get details for the specified NHATS object:
  • https://ssd-api.jpl.nasa.gov/nhats.api?des=99942 (99942 Apophis, default constraints )
  • https://ssd-api.jpl.nasa.gov/nhats.api?des=2000%20SG344&dv=6&dur=360&stay=8&launch=2020-2045 (2000 SG344, constrained)

Query Parameters

This API supports two query modes.

• S - obtain summary data spanning all available NHATS object
• O - obtain details related to a specified NHATS object

The presence of an object selector query parameter (des or spk) distinguishes between the two modes (S and O). That is, if an object selector parameter is specified, an object detail query is executed (mode O). If no object selector parameter is specified, a summary query is executed (mode S).

Note that submitting a query parameter h along with des or spk results in an error because mode O (implied by des or spk) does not match mode S (implied by the presence of h).

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.

Mode S

For summary queries (mode S), there may be no records matching the specified constraints. In such cases, the data count will be zero and the data array will be empty (or null). Normal results will contain a count of the number or records and an array of records with the following content.

• fullname
• constraints used (is this necessary? - convenient when defaults are selected)
• NHATS object details
• NHATS limits minima

The following is an example JSON-format data result matching three objects:

{
  "signature":{"version":"1.0","source":"NASA/JPL NHATS Data API"},
  "count":3,
  "data":[
    {
      "des":"1943",
      "fullname":"1943 Anteros (1973 EC)",
      "orbit_id":"360",
      "h":"15.8",
      "min_size":"1231",
      "max_size":"5507",
      "size":"2300",
      "size_sigma":null,
      "occ":"0",
      "min_dv":{"dv":"11.980", "dur":"354"},
      "min_dur":{"dv":"11.980","dur":"354"},
      "n_via_traj":14,
      "obs_start":"2016-05-11",
      "obs_end":"2017-03-04",
      "obs_mag":"16.96",
      "obs_flag":" ",
      "radar_obs_a":"2026-06-12",
      "radar_snr_a":"860",
      "radar_obs_g":"2026-05-30",
      "radar_snr_g":"34"
    },
    {
      "des":"2000 SG344",
      "fullname":"(2000 SG344)",
      "orbit_id":"15",
      "h":"24.7",
      "min_size":"20",
      "max_size":"89",
      "size":null,
      "size_sigma":null,
      "occ":"2",
      "min_dv":{"dv":"3.550", "dur":"370"},
      "min_dur":{"dv":"3.996","dur":"306"},
      "n_via_traj":3302718,
      "obs_start":"2028-04-28",
      "obs_end":"2028-09-11",
      "obs_mag":"19.11",
      "obs_flag":" ",
      "radar_obs_a":"2028-05-07",
      "radar_snr_a":"3.e3",
      "radar_obs_g":"2028-05-07",
      "radar_snr_g":"59"
    },
    {
      "des": "2006 RH120",
      "fullname":"(2006 RH120)",
      "orbit_id":"48",
      "h":"29.5",
      "min_size":"2.2",
      "max_size":"10",
      "size":null,
      "size_sigma":null,
      "occ":"1",
      "min_dv":{"dv":"3.972", "dur":"450"},
      "min_dur":{"dv":"3.996","dur":"434"},
      "n_via_traj":1277927,
      "obs_start":"2028-06-27",
      "obs_end":"2028-07-12",
      "obs_mag":"23.2",
      "obs_flag":" ",
      "radar_obs_a":null,
      "radar_snr_a":null,
      "radar_obs_g":null,
      "radar_snr_g":null
    }
  ]
}

Mode O

For object detail queries (mode O), it is possible to get no matching results for a valid NHATS object if the constraints are too limiting. In such cases, the JSON payload will contain an error keyword with appropriate message.

{ "error" : "no matching results for specified object and constraints" }

Similarly, in cases where the specified object is not an NHATS object, the JSON payload will contain a message similar to the following.

{ "error" : "specified NHATS object not found"" }

Normal results will contain the following JSON structure.

• fullname
• NNATS object details
• constraints used
• NHATS trajectory details (two trajectory records: min_dv and min_dur)
• plot file image contents base64-encoded (if requested)

The JSON-format result will look something like this:

{
  "signature":{"version":"1.0","source":"NASA/JPL NHATS Data API"},
  "fullname":"(2000 SG344)",
  "orbit_id":"15",
  "h":"24.7",
  "min_size":"20",
  "max_size":"89",
  "size":null,
  "size_sigma":null,
  "occ":"2",
  "min_dv":{"dv":"3.550", "dur":"370"},
  "min_dur":{"dv":"3.996","dur":"306"},
  "n_via_traj":3302718,
  "obs_start":"2028-04-28",
  "obs_end":"2028-09-11",
  "obs_mag":"19.11",
  "obs_flag":" ",
  "radar_obs_a":"2028-05-07",
  "radar_snr_a":"3.e3",
  "radar_obs_g":"2028-05-07",
  "radar_snr_g":"59",
  "plot_base64":"iVBORw0KGgoAAAAN ... AASUVORK5CYII=",
  "computed":"2012-01-06",
  "min_dv_traj":{
    "tid":"889907",
    "dv_total":"3.601",
    "dur_total":"346",
    "dur_out:"137",
    "dur_at":"32",
    "dur_ret":"177",
    "launch":"2028-04-22",
    "c3":"1.737",
    "v_dep_earth":"1.318",
    "dv_dep_park":"3.256",
    "vrel_arr_neo":"0.128",
    "vrel_dep_neo":"0.217",
    "vrel_arr_earth":"0.000",
    "v_arr_earth":"11.141",
    "dec_dep":"-8.723",
    "dec_arr":"-4.771"
  },
  "min_dur_traj":{
    "tid":"913886",
    "dv_total":"3.996",
    "dur_total":"306",
    "dur_out:"137",
    "dur_at":"48",
    "dur_ret":"121",
    "launch":"2028-04-30",
    "c3":"2.197",
    "v_dep_earth":"1.482",
    "dv_dep_park":"3.277",
    "vrel_arr_neo":"0.159",
    "vrel_dep_neo":"0.559",
    "vrel_arr_earth":"0.000",
    "v_arr_earth":"11.231",
    "dec_dep":"-11.175",
    "dec_arr":"4.603"
  }
}

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.

Background Information

The primary NHATS data table as rendered in the current NEO web-site contains a number of parameters. These various parameters require database queries of several different tables in the SBDB. In addition, the data is rendered initially with filter parameters applied.

The main NHATS data table currently allows for filtering by placing user-specified constraints on the following parameters:

• total delta-V (e.g., <= 6 km/s)
• total duration (e.g., <= 360 days)
• stay (e.g., >= 8 days)
• launch window (years: e.g., 2020-2045)
• H magnitude (e.g., <= 26)
• OCC (e.g., <= 7)

Primary NHATS Web-Page Data Table Columns

Detail (object-specific) NHATS Web-Page Data Table Items

Change Log

Version 1.3 (2019 September)

• Updated launch range from 2015-2040 to 2020-2045.

Version 1.2 (2017 March)

• Obsolete plot URL output field plot has been removed. Use plot_base64 instead.

Version 1.1 (2017 February)

• Plot data file contents (base64-encoded) are now optionally available in field plot_base64.
• Prior plot URL output field plot is obsolete and will been removed soon (due to the URL source being removed).
• removed extraneous fields from min_dv_traj and min_dur_traj

Version 1.0 (2016 August)

• Initial release