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!
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.
ssoCard
service in your application. This can be done by using the REST API or by using
the following HTTP request:
[target] is the designation of one or more targets.
The output result is the ssoCard of the target (if only one is requested) or an array of the target ssoCards.
ssoCard for a given target using a simple URL
with a single parameter to select it:
[target_id] is the Quaero ID of the target.
[target] parameter refers to the number (e.g. 100000 or A0000), name (e.g. Pallas), provisional
designation (e.g. 2012 XX21), or alias of the SSO (e.g. 2004 MN4). If the target designation contains a space, it must be replaced
by an underscore or the designation must be placed in quotation marks (e.g. 2012_XX21 or "2012 XX21").
The [target_id] can be obtained by sending a request to the SsODNet.quaero
service. The "id" key in the response provides the expected target identifier (e.g., Io).
In most cases, the identifier corresponds to the official name (e.g., Ceres) or provisional designation
(e.g., 2020 BL6) of the SSO. When the name refers to multiple SSOs (e.g., Io), its ID is composed
of its name followed by the object type, e.g., Io_(Asteroid) and
Io_(Satellite).
To collect ssoCards of multiple targets, you can submit a list of target names separated by commas in the [target] parameter
of the URL, for example Ceres,Pallas,2004_MN4.
You can also submit a text file (Content-Type: text/plain) containing the list of targets, with one identifier per line. The file must
then be sent in a POST request to the SsODNet server. This can be done by using curl, e.g.:
curl -F "targets=@<filename>" "https://ssp.imcce.fr/webservices/ssodnet/api/ssocard.php?q="curl -F "targets=@<filename>" "https://ssp.imcce.fr/webservices/ssodnet/api/ssocard/mytargets"<filename> is the name of your file, and mytargets is any string of your choice.
Please be aware that requesting a large number of ssoCards may take some time and that the volume of data to be downloaded may be very large (~20-30 kB per target).
ssoCards are built?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.
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.
ssoCardThe ssoCard contains the best estimates of dynamic and physical properties of the target encapsulated in a JSON structure defined as follows:
"<sso_id>": {
"id": Unique identifier of the target (string),
"title": Title of the SSO (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),
"metadata": Link to the JSON document providing the metadata (description, unit) of the properties available in the ssoCard (URL)
}
"parameters": { ... }
}The 8 first keys provide the 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 dynamic and physical properties of the target.
Only non-null values are provided. The description and units of the properties are provided in a separate JSON document,
which can be downloaded from the URL provided by the link.metadata key. The structure of parameters
is defined as follows:
"parameters": {
"dynamical": {
"orbital_elements": {},
"proper_elements": {},
"tisserand_parameter": {},
"moid": {},
"source_regions": {},
"family": {},
"pair": {},
"yarkovsky": {}
},
"physical": {
"absolute_magnitude": {},
"diameter": {},
"albedo": {},
"mass": {},
"density": {},
"hill_sphere_radius": {},
"taxonomy": {},
"thermal_inertia": {},
"spins": {},
"phase_functions": {},
"colors": {}
},
"eq_state_vector": {
"ref_epoch": ,
"position": [],
"velocity": [],
}Each property is documented by bibliographic references ("bibref": []), and in most
cases, bibliographic references of the method used to obtain or compute the property ("method": []).
Each property contains also an object "links" which provides the URL to retrieve
the values used to estimate the best value of the given property (key "selection"), and all
values available for the property (key "datacloud"). Some computed properties which are not
stored in the datacloud database do not have links.