Mission Design API

Version: 1.0 (2018 March)

This API provides access to the JPL/SSD small-body mission design suite. The following operation modes are available:

  • Mode Q (query) - this is the standard mode, which retrieves the pre-computed mission options and low-thrust delta-V estimates stored in the small-body database.
  • Mode M (map) - additional information is returned when operating the API in map mode. Apart from the information provided in query mode, the API will generate the complete dataset in order to plot time of flight vs departure date maps displaying different parameters. Mode M is an extension of mode Q.

HTTP Request

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

Example Queries

  • Mode Q - Given an object identifier, return the pre-computed mission options stored in the Small-Body Database.

https://ssd-api.jpl.nasa.gov/mdesign.api?des=2012%20TC4 - Asteroid 2012 TC4

https://ssd-api.jpl.nasa.gov/mdesign.api?des=1&class=true - Asteroid 1 Ceres

https://ssd-api.jpl.nasa.gov/mdesign.api?sstr=apophis - Asteroid 99942 Apophis

  • Mode M - In addition to querying the database like in mode Q, compute all mission options to the specified target within certain ranges of launch dates and times of flight.

https://ssd-api.jpl.nasa.gov/mdesign.api?des=2012%20TC4&mjd0=58490&span=3652&tof-min=10&tof-max=365&step=2 - Missions to asteroid 2012 TC4

https://ssd-api.jpl.nasa.gov/mdesign.api?des=1&mjd0=59000&span=1800&tof-min=120&tof-max=1500&step=5 - Missions to 1 Ceres

Query Parameters

The target body must be specified (via des, spk, or sstr), no matter the operation mode.

  • Mode M - in addition to the object identifier, the user must specify the range of launch dates and times of flight to be explored by the search algorithm.
Parameter Type Allowable Values Default Modes Description
des string     all designation (provisional or IAU-number) of the desired object (e.g., 2015 AB or 141P or 433). NOTE: when submitting a des containing a space in your query string, you must replace the space with %20, for example 2015%20AB. Do not use des if spk or sstr are specified.
spk int     all SPK-ID of the desired object (e.g., 2000433). Do not use spk if des or sstr are specified.
sstr string     all object search string: designation in various forms (including MPC packed form), case-insensitive name, or SPK-ID; designation can be an alternate provisional designation; examples: atira, 2003 CP20, 2003cp20, K03C20P, 163693, 2163693. Do not use sstr if des or spk are specified.
class boolean   false all if set to true, return the orbit class in human-readable format instead of the three-letter code (default false).
mjd0 int [33282,73459]   M first launch date to be explored (Modified Julian Date)
span int [10,9200]   M duration of the launch-date period to be explored (days)
tof-min int [10,9200]   M minimum time of flight to be considered (days)
tof-max int [10,9200]   M maximum time of flight to be considered (days)
step int 1,2,5,10,15,20,30   M time step used to advance both the launch date and the time of flight (days). The size of the transfer map is limited to 1,500,000 points. Consequently, if the requested configuration leads to too many points, the API will return with code 200 and an error message in the JSON payload.

NOTE: Modified Julian Date (MJD) = JD - 2400000.5

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":{"source":"version":"1.0","NASA/JPL ... API"}

Data are returned in JSON format.

The JSON payload will always contain an object that presents information about the small body being considered. The attributes of this object are:

  • des - the primary designation of the object.
  • fullname - the full name of the object.
  • spkid - the primary SPK-ID of the object.
  • orbit_class - the orbit class of the object. If class is false, the orbit class is given by a three-letter code. If set to true, the full name of the orbit class is returned instead.
  • condition_code - condition code of the orbit solution: orbit uncertainty estimate 0-9, with 0 being good, and 9 being highly uncertain.
  • data_arc - number of days spanned by the data-arc the orbit solution was computed from.
  • orbit_id - the current orbit solution of the specified small body.
  • md_orbit_id - the orbit solution that was used to compute the data in the JSON payload. If md_orbit_id does not match orbit_id and the API is operating in mode M, the list of pre-computed missions might not be consistent with the pork-chop plot data. See API internal exceptions for more information about this exception.

In both mode Q and mode M, the API will return the data that was pre-computed and stored in the Small Body Database:

  • dv_lowthrust - Edelbaum’s low-thrust delta-V estimates, which provide time-free approximations not accounting for phasing. It will only be provided for elliptic orbits. This object has two attributes:
    • const - the thrust acceleration is assumed constant.
    • sep - approximates a solar electric propulsion system, following a 1 / r2 law.
  • fields - the table containing the list of pre-computed missions is provided in the form of a 2D array. fields is simply the header of this table. The columns of the table, listed in fields, are:

    • MJD0 - departure date from Earth (Modified Julian Date).
    • MJDf - arrival date to target (Modified Julian Date).
    • vinf_dep - magnitude of the departure V-infinity vector (km/s).
    • vinf_arr - magnitude of the arrival V-infinity vector (km/s).
    • phase_ang - Sun phase angle: angle between the arrival V-infinity vector and Sun-target position vector at arrival (deg).
    • earth_dist - distance from the spacecraft to Earth at the date of arrival (au).
    • elong_arr - solar elongation at arrival (Sun-Earth-probe angle): apparent angle between the Sun and the target as seen from Earth at the date of arrival (deg).
    • decl_dep - declination of the outgoing V-infinity vector referred to the Earth’s mean equator (deg).
    • approach_ang - approach angle to the target (pump angle): angle between the arrival V-infinity vector and the velocity vector of the target body (deg).
  • selectedMissions - the 2D array containing the list of pre-computed trajectories stored in the Small Body Database. These solutions capture the optimal launch windows (in terms of departure C3), as well as minimum time and minimum arrival V-infinity options under certain C3 constraints. Each row corresponds to a different mission, and the columns are defined by fields.

Mode Q

No additional information will be provided when operating in query mode (Q). It is possible that no feasible transfer options were found to the specified object. In that case, the JSON payload will include an error message (see API internal exceptions).

The JSON payload will be similar to:

{
  "signature" : {"version":"1.0","source":"NASA/JPL Mission Design API"},
  "object" : {
    "des" : "1",
    "fullname" : "1 Ceres",
    "spkid" : "2000001",
    "orbit_class" : "MBA",
    "condition_code" : "0",
    "data_arc" : "24437",
    "orbit_id" : "34",
    "md_orbit_id" : "34"
  },
  "dv_lowthrust": {
    "sep": 3.893999531963410e+01,
    "const": 1.336244672239606e+01
  },
  "fields": ["MJD0","MJDf","vinf_dep","vinf_arr","phase_ang","earth_dist","elong_arr","decl_dep","approach_ang"],
  "selectedMissions": [[61745,62125,11.3777,6.3766,52.45,3.8475,4.58,5.98,137.61],
    [62265,62565,11.26,9.9863,26.18,3.9258,12.22,-69.43,116.36],
    [65535,65820,11.177,10.6303,25.75,3.8817,20.29,-69.69,112.90],
    [62580,64015,10.9125,6.7504,58.75,3.9083,15.97,-55.14,135.37],
    [58070,58320,10.8491,9.6527,33.45,3.2371,41.76,69.94,120.41],
    [66465,66705,10.8218,10.6407,29.94,3.1188,48.58,70.36,117.04],
    ...
  ]
}

NOTE: the array selectedMissions in the example above has been reduced for convenience.

Mode M

In map mode M, the JSON payload also includes several 2D arrays containing information for representing time of flight vs departure date maps:

  • vinf_dep - magnitude of the departure V-infinity vector (km/s).
  • vinf_arr - magnitude of the arrival V-infinity vector (km/s).
  • phase_ang - Sun phase angle: angle between the arrival V-infinity vector and Sun-target position vector at arrival (deg).
  • earth_dist - distance from the spacecraft to Earth at the date of arrival (au).
  • elong_arr - solar elongation at arrival (Sun-Earth-probe angle): apparent angle between the Sun and the target as seen from Earth at the date of arrival (deg).
  • decl_dep - declination of the outgoing V-infinity vector referred to the Earth’s mean equator (deg).
  • approach_ang - approach angle to the target (pump angle): angle between the arrival V-infinity vector and the velocity vector of the target body (deg).

In addition, the values of the x-_y_ axes of the maps are also provided:

  • dep_date - departure dates from Earth (Modified Julian Date), corresponding to the x-axis.
  • tof - times of flight to the target (days), corresponding to the y-axis.

If dep_date has m elements and tof has n, then the 2D arrays are of dimension n x m.

{
  "signature" : {"version":"1.0","source":"NASA/JPL Mission Design API"},
  "object" : {
    "des" : "1",
    "fullname" : "1 Ceres",
    "spkid" : "2000001",
    "orbit_class" : "MBA",
    "condition_code" : "0",
    "data_arc" : "24437",
    "orbit_id" : "34",
    "md_orbit_id" : "34"
  },
    "dv_lowthrust": {
    "sep": 3.893999531963410e+01,
    "const": 1.336244672239606e+01
  },
  "fields": ["MJD0","MJDf","vinf_dep","vinf_arr","phase_ang","earth_dist","elong_arr","decl_dep","approach_ang"],
  "selectedMissions": [[61745,62125,11.3777,6.3766,52.45,3.8475,4.58,5.98,137.61],
    [62265,62565,11.26,9.9863,26.18,3.9258,12.22,-69.43,116.36],
    [65535,65820,11.177,10.6303,25.75,3.8817,20.29,-69.69,112.90],
    [62580,64015,10.9125,6.7504,58.75,3.9083,15.97,-55.14,135.37],
    [58070,58320,10.8491,9.6527,33.45,3.2371,41.76,69.94,120.41],
    [66465,66705,10.8218,10.6407,29.94,3.1188,48.58,70.36,117.04],
    ...
  ],
  "dep_date": [58022.0,58032.0,58042.0,58052.0,58062.0,58072.0,58082.0,58092.0,58102.0,58112.0,58122.0,58132.0,58142.0,...],
  "tof": [1.2000E+02,1.3000E+02,1.4000E+02,1.5000E+02,1.6000E+02,1.7000E+02,1.8000E+02,1.9000E+02,2.0000E+02,...],
  "vinf_dep": [[2.850E+01,2.602E+01,2.360E+01,2.139E+01,1.957E+01,1.829E+01,...],
    [2.569E+01,2.340E+01,2.117E+01,1.916E+01,1.757E+01,1.653E+01,1.631E+01,...],
    [2.339E+01,2.124E+01,1.918E+01,1.736E+01,1.597E+01,1.515E+01,1.514E+01,...],
    [2.150E+01,1.947E+01,1.755E+01,1.590E+01,1.469E+01,1.406E+01,1.423E+01,...],
    ...],
  "vinf_arr": [[3.697E+01,3.541E+01,3.375E+01,3.203E+01,3.025E+01,2.847E+01,...],
    [3.340E+01,3.198E+01,3.047E+01,2.890E+01,2.729E+01,2.567E+01,2.408E+01,...],
    [3.033E+01,2.902E+01,2.764E+01,2.620E+01,2.473E+01,2.325E+01,2.180E+01,...],
    [2.767E+01,2.645E+01,2.518E+01,2.385E+01,2.250E+01,2.114E+01,1.981E+01,...],
    ...],  
  "phase_ang": [[6.4298E+00,5.8526E+00,5.2606E+00,4.6357E+00,4.0510E+00,...],
    [7.4765E+00,6.7788E+00,6.1325E+00,5.5678E+00,5.2216E+00,5.4052E+00,...],
    [8.7985E+00,8.0183E+00,7.3591E+00,6.8813E+00,6.7419E+00,7.2113E+00,...],
    [1.0339E+01,9.4884E+00,8.8283E+00,8.4330E+00,8.4597E+00,9.1452E+00,...],
    ...],
  "earth_dist": [[1.6063E+00,1.6045E+00,1.6300E+00,1.6808E+00,1.7533E+00,...],
    [1.6045E+00,1.6300E+00,1.6808E+00,1.7533E+00,1.8434E+00,1.9472E+00,...],
    [1.6300E+00,1.6808E+00,1.7533E+00,1.8434E+00,1.9472E+00,2.0605E+00,...],
    [1.6808E+00,1.7533E+00,1.8434E+00,1.9472E+00,2.0605E+00,2.1801E+00,...],
    ...],  
  "elong_arr":[[1.6574E+02,1.6483E+02,1.5656E+02,1.4637E+02,1.3609E+02,...],
    [1.6483E+02,1.5656E+02,1.4637E+02,1.3609E+02,1.2625E+02,1.1700E+02,...],
    [1.5656E+02,1.4637E+02,1.3609E+02,1.2625E+02,1.1700E+02,1.0838E+02,...],
    [1.4637E+02,1.3609E+02,1.2625E+02,1.1700E+02,1.0838E+02,1.0032E+02,...],
    ...],
  "decl_dep": [[2.9591E+01,2.9972E+01,3.1243E+01,3.3468E+01,3.6492E+01,...],
    [3.1698E+01,3.2147E+01,3.3593E+01,3.6064E+01,3.9305E+01,4.2706E+01,...],
    [3.4107E+01,3.4614E+01,3.6226E+01,3.8918E+01,4.2302E+01,4.5564E+01,...],
    [3.6815E+01,3.7361E+01,3.9123E+01,4.1994E+01,4.5426E+01,4.8384E+01,...],
    ...],
  "approach_ang": [[9.3004E+01,9.2422E+01,9.2084E+01,9.2059E+01,9.2424E+01,...],
    [9.4360E+01,9.3829E+01,9.3555E+01,9.3608E+01,9.4066E+01,9.5026E+01,...],
    [9.5742E+01,9.5257E+01,9.5047E+01,9.5181E+01,9.5737E+01,9.6817E+01,...],
    [9.7161E+01,9.6718E+01,9.6571E+01,9.6788E+01,9.7449E+01,9.8657E+01,...],
    ...]
}

NOTE: the arrays presented in this example JSON file have been reduced for convenience.

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: data returned (may be empty) or an error message (see API internal exceptions)
300 Multiple Choices the specified parameters matched more than one object: matching list provided (see Multiple Objects Matching sstr)
400 Bad Request the request contained invalid keywords and/or content or used a request-method other than GET or POST (details returned in the JSON payload)
405 Method Not Allowed the request used a method other than GET or POST
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

API Internal Exceptions

Normal returns with HTTP code 200 might include error messages or warnings related to special exceptions:

  • { "message" : "specified object was not found" } - the des, spk, or sstr provided was not found in the Small Body Database. No data will be provided.
  • { "warning" : "pre-computed missions are based on an outdated orbit solution" } - the mission options stored in the Small Body Database were computed with an orbit solution that is no longer the latest, i.e. orbit_id does not match md_orbit_id. All data will still be provided.
  • { "warning" : "no pre-computed missions for specified object" } - no feasible missions were found under the default constraints. At least the signature and object (mode Q only) objects will be provided. If the orbit is closed, dv_lowthrust will also be provided.
  • { "warning" : "orbit solution is highly uncertain (condition_code >= 7)" } - based on its condition code, the current orbit solution is highly uncertain. All data will still be provided.

Multiple Objects Matching sstr

For normal cases where the query matches a single object, the complete data set is returned in JSON-format. In cases where more than one object matches, a list is returned with a primary designation pdes and corresponding full-name for each matching object. From pdes, it should be possible to submit a new query with des set to the pdes of interest. Here’s an example result from the query sstr=141P.

{
  "signature":{"version":"1.0","source":"NASA/JPL Mission Design API"},
  "code": 300,
  "message": "specified query matched more than one object",
  "list": [
    { "pdes": "141P", "name": "141P/Machholz 2" },
    { "pdes": "141P-A", "name": "141P/Machholz 2-A" },
    { "pdes": "141P-D", "name": "141P/Machholz 2-D" }
  ]
}

From these results, it should be possible to provide a list of links to the appropriate URL with the corresponding pdes set in des for each possible match. Assuming the user wanted 141P (parent comet, no fragment letter), they would use des=141P which would match only that designation (unlike using sstr=141P which will match the parent and both fragments).

Change Log

Version 1.0 (March 2018)

  • Initial release.