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


Example Queries

  • (return all available data except orbits)
  • (return available data including orbit for 22 Kalliope)

Query Parameters

Parameter Type Default Description
des string none only data for the object matching this designation (e.g., 2004 VB or 45P or 433) [NOTE: when submitting a des containing a space in your query string, you must replace the space with %20, for example 2004%20VB]
spk int none only data for the object matching this SPK-ID (e.g., 2000433 )
kind string none limit data to objects of the specified kind (a=asteriod, an=numbered-asteroids, au=unnumbered-asteroids, c=comets, cn=numbered-comets, cu=unnumbered-comets, n=numbered-objects, and u=unnumbered-objects)
orb boolean false include default orbit (if any) for selected satellite(s)
sigma boolean false include orbital element 1-sigma values (uncertainties) where available
phys-par boolean false include specific physical parameters (if any) for selected satellite(s)
fullname boolean false include fullname of the primary body on output
class boolean false include orbital class of the primary body on output
confirmed string all all for all satellites (confirmed or not), Y for only confirmed satellites, or N for only unconfirmed satellites; not valid when using query parameters des or spk

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


  • 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


  • 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


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


  • (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.

Field Option Description
pdes   primary designation (des) of the primary body (pb) asteroid or comet (e.g., 443, 2019 NX1)
confirmed   flag indicating whether or not this satellite is confirmed according to the reference (Y=confirmed, N=not confirmed)
prov_year   discovery year
prov_num   provisional discovery number within the discovery year (e.g., “1”)
iau_num   IAU number (if any)
iau_name   IAU satellite name (e.g., “Dactyl”)
sat_fullname   fully formatted complete satellite designation (e.g., “S/1997 (3671) 1”)
ref   publication reference for the satellite
notes   general notes
fullname fullname primary body fullname (e.g., 433 Eros (A898 PA)
class   primary body orbital class code (e.g., MBA)
class_name class primary body orbital class name (e.g., Main-belt Asteroid)
kind   primary body object kind (e.g., “an” for numbered asteroid)
prefix   primary body comet designation prefix (typically null)

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.

Field Units Description
oid   orbit reference ID
epoch   epoch of osculating elements (TDB) in Julian day form
frame   Reference frame (example, “EQ” for equatorial, “EC” for ecliptic)
equinox   (J2000, B1950 - frame implied)
e   eccentricity
a km semi-major axis
q km perihelion distance
i deg inclination
om deg longitude of the ascending node
w deg argument of perihelion
tp d time of perihelion passage (TDB) formatted as Julian day
ma deg mean anomaly
per h orbital period
dn_dt deg/y^2 rate of change of mean motion
n deg/d mean motion
a_D   semi-major axis scaled by the diameter of the primary body
ref   orbit reference publication
notes   notes

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

Field Units Description
sigma_e   1-sigma eccentricity
sigma_a km 1-sigma semi-major axis
sigma_q km 1-sigma perihelion distance
sigma_i deg 1-sigma inclination
sigma_om deg 1-sigma longitude of the ascending node
sigma_w deg 1-sigma argument of perihelion
sigma_tp d 1-sigma time of perihelion passage
sigma_ma deg 1-sigma mean anomaly
sigma_per h 1-sigma orbital period
sigma_dn_dt deg/y^2 1-sigma mean motion rate of change
sigma_n deg/d 1-sigma mean motion
sigma_a_D   1-sigma scaled semi-major axis

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

Field Units Description
diameter km effective satellite diameter
extent km tri(or bi)-axial satellite dimensions
rot_per h satellite rotation period
GM km^3/s^2 standard gravitational parameter: product of the mass (M) and gravitational constant (G)
density g/cm^3 bulk density

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

Field Description
value value of the associated physical parameter
sigma 1-sigma of the value
ref reference publication
notes notes

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.

HTTP Code Description Typical Usage
200 OK normal successful result: data returned
400 Bad Request the request contained invalid keywords and/or content: details returned
405 Method Not Allowed the request used an incorrect method (see the HTTP Request section)
500 Internal Server Error 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 (2020 August)

  • Initial release