Small-Body Satellites API

Version: 1.0 (2020 August)
change log

The small-body satellites API provides a method of requesting data related to satellites of asteroids and comets.

HTTP Request

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

Example Queries

• https://ssd-api.jpl.nasa.gov/sb_sat.api (return all available data except orbits)
• https://ssd-api.jpl.nasa.gov/sb_sat.api?des=22&orb=1 (return available data including orbit for 22 Kalliope)

Query Parameters

Satellite Designations

Asteroid satellite designations are separated into two kinds: provisional and permanent. Both provisional and permanent designations are assigned by the IAU.

Provisional Designations

The provisional designation of an asteroid satellite is defined as follows:

S/discovery-year (asteroid-primary-designation) satellite-number

where

• discovery-year - is the year the satellite was discovered
• asteroid-primary-designation - is the primary designation of the asteroid (primary body of the system)
• satellite-number - is the discovery sequence number in the discovery-year of the satellite

Examples:

• S/1997 (3671) 1 - the first IAU-numbered satellite of asteroid 3671 Dionysus
• S/2000 (2000 DP107) 1 - the first IAU-numbered satellite of (then unnumbered) asteroid 2000 DP107

Permanent Designations

The permanent designation for an asteroid satellite is defined as follows:

(asteroid-IAU-number) asteroid-IAU-name IAU-number

where

• asteroid-IAU-number - is the IAU number of the asteroid (primary body of the system)
• asteroid-IAU-name - is the IAU name of the asteroid (primary body of the system)
• IAU-number - is the IAU number of the satellite in Roman numeral form

Note that a satellite permanent designation cannot be assigned until the primary body of the system is numbered and named.

Examples:

• (243) Ida I
• (216) Kleopatra II

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 as a single object (hash-table). The number of records contained in the object is indicated in the “count” key. In cases where user-specified constraints are too tight (no matching results), only the “count” and “signature” keys are returned, as in the following example.

{ "count":0, "signature":{"version":"1.0","source":"NASA/JPL Small-Body Satellites API"} }

Each record is provided as an element of the “data” object and each record is an object with the following items: “sat”, “orbit”, and “phys_par” (where “orbit” is only output when the orb query parameter is set and “phys_par is only output when the phys-par query parameter is set”).

The “sat” object items are defined as follows.

Suspected satellites, based on the description in the reference, are marked as [unconfirmed] in the notes column.

Additional (optional) “orbit” object items are defined as follows (see orb query parameter):

Orbital elements are with respect to the primary body. Note that even when orb is set, if the satellite has no orbit data, the “orbit” object will not be output.

Optional sigma “orbit” object items output when sigma is set:

Additional (optional, see phys-par query parameter) physical parameter “phys_par” object items represent available physical parameters as follows:

For each of the above physical parameter objects, the following items are output:

Sample Data Output

{
  "signature" : {"source" : "NASA/JPL Small-Body Satellites API", "version" : "1.0"},
  "count" : "2",
  "data" : [
    {
      "sat" : {
        "class" : "MBA",
        "iau_name" : "Petit-Prince",
        "iau_num" : "1",
        "kind" : "an",
        "notes" : null,
        "pdes" : "45",
        "prefix" : null,
        "prov_num" : "1",
        "prov_year" : "1998",
        "ref" : "Merline et al. (1999), IAUC 7129",
        "sat_fullname" : "(45) Eugenia I Petit-Prince"
      }
    },
    {
      "sat" : {
        "class" : "MBA",
        "iau_name" : null,
        "iau_num" : null,
        "kind" : "an",
        "notes" : null,
        "pdes" : "45",
        "prefix" : null,
        "prov_num" : "1",
        "prov_year" : "2004",
        "ref" : "Marchis et al. (2007), IAUC 8817",
        "sat_fullname" : "S/2004 (45) 1"
      }
    }
  ]
}

{
  "signature" : {"source" : "NASA/JPL Small-Body Satellites API", "version" : "1.0"},
  "count" : "1",
  "data" : [
    "sat" : {
       "class" : "APO",
       "iau_name" : null,
       "iau_num" : null,
       "kind" : "an",
       "notes" : null,
       "pdes" : "185851",
       "prefix" : null,
       "prov_num" : "1",
       "prov_year" : "2000",
       "ref" : "Margot et al. (2002), Science, 296",
       "sat_fullname" : "S/2000 (185851) 1"
    },
    {
      "orbit" : {
        "a" : "2659",
        "a_D" : null,
        "dn_dt" : null,
        "e" : "0.019",
        "epoch" : null,
        "equinox" : "J2000",
        "frame" : "EC",
        "i" : "12",
        "ma" : null,
        "n" : null,
        "notes" : null,
        "oid" : "0",
        "om" : "24",
        "per" : "42.1344",
        "q" : null,
        "ref" : "Naidu et al. 2015",
        "tp" : null,
        "w" : null
      },
      "phys_par" : {
        "GM" : {
          "notes" : null,
          "ref" : "Naidu et al. 2015",
          "sigma" : "0.14e-9",
          "value" : "1.2e-9"
        },
        "density" : {
          "notes" : null,
          "ref" : "Naidu et al. 2015",
          "sigma" : "0.230",
          "value" : "1.047"
        },
        "diameter" : {
          "notes" : null,
          "ref" : "Naidu et al. 2015",
          "sigma" : "0.019",
          "value" : "0.316"
        },
        "extent" : {
          "notes" : null,
          "ref" : "Naidu et al. 2015",
          "sigma" : "0.023 x 0.019 x 0.016",
          "value" : "0.377 x 0.314 x 0.268"
        },
        "rot_per" : {
          "notes" : null,
          "ref" : "Naidu et al. 2015",
          "sigma" : "0.48",
          "value" : "42.48"
        }
      }
    }
  ]
}

HTTP Response Codes

All errors are returned via appropriate HTTP response codes.

Change Log

Version 1.0 (2020 August)

• Initial release