SsODNet

ssocard

Best estimate of SSO properties

The method ssocard is intended to people who need to retrieve the best estimates of the dynamical and physical properties of solar system objects, based on the data aggregated in SsODNet.datacloud.

Use our dedicated Web form to display the properties of your preferred asteroid!

rocks API

The best friendly way to retrieve data from SsODNet.ssoCard is to use the “rocks” API. This is a command-line Python software allowing to request SsODNet with simple and natural commands. Read the documentation for more information and tutorials.

HTTP Request

If you are a software/solutions developer, you might want to include the SsODNet ssoCard service in your application. This can be done by using the REST API or by using the following HTTP request:
https://ssp.imcce.fr/webservices/ssodnet/api/ssocard.php?q=[target]
where [target] is the designation of the target.

The output result is the ssoCard of the target stored in a JSON object.

Examples

REST API

This API allows to submit requests to the ssoCard service by using a simple URL with a single parameter to select the target:
https://ssp.imcce.fr/webservices/ssodnet/api/ssocard/[target]
where [target] is the designation of the target.
Examples

Target designation

The [target] parameter refers to the unique identifier assigned to each target. Most of the time this is the official name (e.g. Ceres) or the provisional designation (e.g. 2020 BL6) of the SSO. When the name refers to several SSOs (e.g. Io), the name is suffixed with the type of object, e.g. Io_(Asteroid) and Io_(Satellite).

This unique identifier can be obtained by requesting the SsODNet.quaero service. The "id" key of the response supplies the identifier expected by the SsODNet.ssoCard service (e.g. Io).

To collect the ssoCard of several targets, you have to provide a text file (Content-Type: text/plain) containing the list of targets, one identifier per line. The file must then be sent in POST request to the SsODNet server. This can be achieved by using curl, e.g.: 

curl -F "targets=@<filename>" "https://ssp.imcce.fr/webservices/ssodnet/api/ssocard.php?q="
or with the REST API:
curl -F "targets=@<filename>" "https://ssp.imcce.fr/webservices/ssodnet/api/ssocard/mytargets"
where <filename> is the name of your file, and mytargets is any string of your choice.

How ssoCards are built?

A ssoCard is a structured object containing the best estimates of dynamical and physical properties of a Solar system object. The properties are extracted among all the data gathered in the SsODNet.datacloud database. Some properties have a unique value provided by a resource (dataset, scientific paper), and some of them have a multitude of values coming from various measurements, or technics, surveys, etc.

▸ When a property has a unique value, or when the different values of the property cannot be averaged, e.g. orbital elements, the selection of the best value is based on the choice of the resource, e.g. ASTORB or MPCORB for orbital elements.

▸ When multiple values of a given property exist, we have set up a decision tree to choose the best value or to compute its weighted mean. As an example, the following figure enlightens how the taxonomy of a SSO is choosen.

Decision tree to get the best taxonomical class of a SSO
Taxonomy flow chart

The choice we made to select data among resources, as well as the decision trees we have set up for multiple values, are described in Berthier et al., 2023. An overview of the ordered list of methods used to compute the best-estimate of properties is proposed in Howto ssoCard section.

Structure of a ssoCard

The ssoCard contains the best estimates of physical and dynamical properties of the target encapsulated in a JSON structure defined as follows:

Test Example

"<sso_id>": { 
   "id": Unique identifier of the target (string),
   "name": Name of the SSO (string),
   "number": Number of the SSO (int),
   "type": Type of the SSO (string),
   "class": Dynamical class of the SSO (string),
   "parent": Name of the parent of the SSO (string),
   "system": Name of the planetary system to which the SSO belongs (string),
   "ssocard": {
      "version": Version number of ssoCard data model (string),
      "datatime": Date and time of creation of the ssoCard (ISO date)
   },
   "link": {
      "self": Direct link to retrieve the ssoCard (URL),
      "quaero": Direct access to SsODNet.quaero for the target (URL),
      "description": Link to the JSON document providing the description of the properties available in the ssoCard (URL),
      "unit": Link to the JSON document providing the description of the property units of the ssoCard (URL),
   }
   "parameters": { ... },
   "datacloud": { ... }
}

The 7 first keys provide the simplified identity of the target provided by SsoDNet.quaero. The full identity can be retrieved using the URL provided by the key: link.quaero.

parameters is an object containing the dynamical and physical properties of the target. Only not null values are provided. The description and units of properties are provided in separate JSON documents, downloadable from the URL given by the keys link.description and link.unit. The structure of parameters is defined as follows:

"parameters": {
   "dynamical": {
      "orbital_elements": {},
      "proper_elements": {},
      "family": {},
      "pair": {},
      "tisserand_parameter": {},
      "yarkovsky": {}
   },
   "physical": {
      "albedo": {},
      "absolute_magnitude": {},
      "colors": {},
      "density": {},
      "diameter": {},
      "mass": {},
      "phase_function": {},
      "spin": {},
      "taxonomy": {},
      "thermal_inertia": {}
   },
   "eq_state_vector": {
      "ref_epoch": ,
      "position": [],
      "velocity": [],
}

Each property is documented by a bibliographic reference ("bibref": []), and in most cases a bibliographic reference of the method used to obtain or compute the property ("method": []).

"datacloud" is an object containing links to retrieve all values used to estimate the best value of the given property. Each link points to the corresponding collection in the datacloud for the target. The computed properties which are not stored in the datacloud do not have links.