To stay informed of the latest events and advances of the Quaero API you can subscribe to our ssp-announce.imcce mailing list. This includes announcements about releases, new Quaero capabilities and downtimes. This is a low volume and read only list.
To subscribe to this list, please send an email to sympa@sympa.obspm.fr with the following subject: subscribe ssp-announce.imcce
The Quaero API is part of the SsODNet API. It is intended to provide the following services:
It is a REST API that returns standard HTTP codes, JSON formatted responses and supports cross-origin resource sharing.
The designations of solar system objects come from the following sources:
A collection is a group of resources. Some methods of this API return a collection.
{
"data": [{...},{...}...],
"total": integer,
"links": {
"next": string,
"previous": string
}
}
| Field | Type | Description |
|---|---|---|
data |
array |
List of resources in the collection. |
total |
integer |
Number of resources returned by the query. |
links |
object |
When the number of resources returned is too large, the response is paginated. |
When a resource is returned inside a collection a links field is also added into the resource. It defines the self relation type which is the endpoint that will return the resource itself.
Requests that return a collection will be paginated to 10 resources by default.
This API provides an offset-based pagination. A paginated response contains a links object with the following fields:
| Field | Type | Description |
|---|---|---|
next |
string |
Endpoint that will return the next page of data. |
previous |
string |
Endpoint that will return the previous page of data. |
The absence of the links object means that the full collection is returned. If the next field is not included, this is the last page of data and if the previous field is not included this is the first page of data.
The Quaero API provides links to navigate from a resource to another. Each link is defined as a attribute-value pair where attribute indicates the type of the link and where value is the link's URI.
The Quaero API uses standard HTTP response codes to indicate the success or failure of a request. The error messages returned are in JSON format.
The Quaero API supports cross-origin resource sharing (CORS) for AJAX requests from any origin.
If you use SsODNet/Quaero REST API in your research or if you implement it into your application, the following acknowledgment would be appreciated: Powered by IMCCE - SsODNet/Quaero REST API.
Below are some examples of use cases. However, this is not a reference and not all the Quaero API are shown.
Quaero provides a fast search engine to explore solar system objects (Sso).
The /sso endpoint finds any Sso whose designation matches a given term.
https://api.ssodnet.imcce.fr/quaero/1/sso?q=1899 Test
https://api.ssodnet.imcce.fr/quaero/1/sso?q=1899&type=Dwarf Planet Test
https://api.ssodnet.imcce.fr/quaero/1/sso/Ceres Test
The /sso/search endpoint allows you to build complex queries using field names, logical operators and even more.
https://api.ssodnet.imcce.fr/quaero/1/sso/search?q=ceres pallas vesta Test
https://api.ssodnet.imcce.fr/quaero/1/sso/search?q=system:Mars -type:(Spacecraft OR Spacejunk) Test
https://api.ssodnet.imcce.fr/quaero/1/sso/search?q=class:(mb AND inner) AND 1979 Test
The /sso/{sso-id}/resolver endpoint allows to resolve a solar system object into celestial coordinates.
https://api.ssodnet.imcce.fr/quaero/1/sso/Saturn/resolver Test
https://api.ssodnet.imcce.fr/quaero/1/sso/Saturn/resolver?epoch=2457754.512 Test
The Quaero API can be used to provide an autocomplete service that returns solar system object suggestions as a user types. Demo.
More examples about the search capability provided by Quaero can be found in SsODNet documentation ref..
The base URL for the Quaero REST API in the version defined in this document is
https://api.ssodnet.imcce.fr/quaero/1
The Coosys object ref. represents the celestial coordinate reference system to which the components of a position on the celestial sphere refer.
{
"equinox": string,
"system": string
}
| Field | Type | Description |
|---|---|---|
equinox |
string |
Defines the epoch of the equinox of the reference system. |
system |
string |
Specifies the coordinate system. |
The Quaero API uses the International Celestial Reference System (ICRS) to defined the position of a solar system object. It is defined by the following Coosys object:
{
"equinox": "J2000",
"system": "ICRS"
}
The Position object represents the position of a solar system object on the celestial sphere at a given epoch. GeoJSON ref. is used to format this object.
According to the GeoJSON RFC, Quaero API uses its own coordinate reference system to define the coordinates of a solar system object. Our coordinate reference system is fully defined by the Coosys object.
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [float],
},
"properties": {
"epoch": float,
"coosys" : object
}
}
| Field | Type | Description |
|---|---|---|
epoch |
float |
Requested UTC epoch (in julian day). |
coordinates |
array of float |
Coordinates of the Sso. [RA (in hour), DEC (in degree), D (in au)] |
coosys |
Coosys |
Celestial coordinate reference system. |
According to the celestial coordinate system used by Quaero, RA refers to the right ascension, DEC to the declination and D to the distance to geocenter in the geocentric equatorial astrometric J2000 frame.
The Sso object represents a solar system object and contains information about it.
{
"name": string",
"id": string,
"ephemeris": boolean,
"aliases": [
string
],
"system": string,
"parent": string,
"type": string,
"class": [
string
]
}
The absence of a field in the object means a nulled field or an empty set.
| Field | Type | Description |
|---|---|---|
name |
string |
Name of the Sso. |
id |
string |
Identifier that SsoDNet uses to uniquely identify the Sso. |
updated |
string |
Last update of the Sso in SsODNet (YYYY-MM-DD). |
ephemeris |
boolean |
Indicates whether the ephemeris are available for the Sso. |
aliases |
array of string |
List of other known names of the Sso. |
system |
string |
Name of the dynamical system containing the Sso. |
parent |
string |
Name of the parent object of the Sso. |
type |
enum |
Type of the Sso. |
class |
array of string |
List of classes of the Sso. |
The value of the type field represents the type of the Sso. Currently Quaero supports the following types:
The class field refers to the classification of a solar system object. This classification depends on the type of the object and the characteristics of their orbits. A Sso can have several classes. The values in this array are ordered thus it is possible to get the hierarchy. All solar system objects classes are documented in SkyBoT documentation ref..
These lists can evolve in the future. To get an up to date list of supported values, request OPTIONS /sso.
A dynamical system is a set of solar system objects in orbit around a star or another solar system object. In Quaero a system is named by the name of the main body in the system.
Retreives information about an existing solar system object.
GET /sso/{sso-id}
sso-id The identifier of the Sso (case sensitive and URL-encoded).
Sso object.
404 The requested Sso does not exist in SsODNet.
502 Something went wrong on SsODNet's end.
GET /sso/Mars
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
"name": "Mars",
"id": "Mars",
"ephemeris": true,
"aliases": ["4"],
"system": "Mars",
"parent": "Sun",
"type": "Planet",
"updated": "2017-01-23"
}
GET /sso/P/2000_S1
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
"class": ["Short-period","Halley-type"],
"parent": "Sun",
"aliases": ["P/Skiff","2000 S1"],
"system": "Sun",
"ephemeris": true,
"id": "P/2000_S1",
"type": "Comet",
"name": "P/2000 S1",
"updated": "2017-01-23"
}
Returns a collection of relevant solar system objects matching a specified query. This method is intended to provide a minimal search capability based only on the name and aliases fields of the Sso.
The search term can contain one or several tokens. When multiple tokens are set, a logical AND is applied.
It is also possible to search for Sso amongst one type of Sso using type parameters.
GET /sso
q (string, required) Search terms (URL-encoded).
type (string, optional) The type of the Sso (case sensitive).
offset (integer, optional, default 0) Offsets the start of each page by the number specified.
limit (integer, optional, default 10) Number of sso that are returned in each page.
Collection of Sso resources.
400 Bad Request
502 Something went wrong on SsODNet's end.
GET /sso?q=io
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
"data": [
{
"name": "Io",
"id": "Io_(Satellite)",
"ephemeris": true,
"aliases": ["501","J-1","J-I"],
"system": "Jupiter",
"parent": "Jupiter",
"type": "Satellite",
"updated": "2017-01-23",
"links": {
"self": "https://api.ssodnet.obspm.fr/quaero/1/sso/Io_(Satellite)"
}
},
{
"name": "Io",
"id": "Io_(Asteroid)",
"aliases": ["85","1899 LA","I99L00A","1899 UA","I99U00A"],
"ephemeris": true,
"class": ["MB","Middle"],
"system": "Sun",
"parent": "Sun",
"type": "Asteroid",
"updated": "2017-01-23",
"links": {
"self": "https://api.ssodnet.obspm.fr/quaero/1/sso/Io_(Asteroid)"
}
},
{...}
],
"total":3
}
GET /sso?q=io&type=Asteroid
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
"data": [
{
"class": ["MB","Middle"],
"parent": "Sun",
"aliases": ["85","1899 LA","I99L00A","1899 UA","I99U00A"],
"system": "Sun",
"ephemeris": true,
"id": "Io_(Asteroid)",
"type": "Asteroid",
"links": {
"self": "https://api.ssodnet.imcce.fr/quaero/1/sso/Io_(Asteroid)"
}
"name": "Io",
"updated": "2017-01-23"
}
]
"total": 1,
}
GET /sso?q=2010
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
"data": [{...}...],
"total": 59370,
"paging": {...}
}
GET /sso?q=2010 GD159
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
"data":[
{
"name": "2015 BA307",
"id": "2015_BA307",
"aliases": ["K15BU7A","2010 AE110","K10AB0E","2010 GD159","K10GF9D","2010 NM7","K10N07M"],
"ephemeris": true,
"class": ["MB","Outer"],
"system": "Sun",
"parent": "Sun",
"type": "Asteroid",
"updated": "2017-01-23",
"links": {
"self": "https://api.ssodnet.obspm.fr/quaero/1/sso/2015_BA307"
}
}
],
"total": 1
}
Returns the 3D geocentric equatorial astrometric J2000 position of solar system object.
GET /sso/{sso-id}/resolver
sso-id The identifier of the Sso (case sensitive and URL-encoded).
epoch (float, optional, default to current date) Epoch expressed in julian day.
Position object.
400 Bad Request. Also returned when the requested epoch is outside the interval of calculation of the theory INPOP13C.
404 The requested Sso does not exist in SsODNet.
501 The resolver is not implemented for this Sso.
502 Something went wrong on SsODNet's end.
A links field is also added into the properties field of the Position object. It defines the self relation type which is the endpoint that will return this position.
GET /sso/Mars/resolver
HTTP/1.1 200 OK
Content-Type: application/geo+json;charset=utf-8
{
"properties": {
"epoch": 2457772.0749884,
"coosys": {
"equinox": "J2000",
"system": "ICRS"
},
"links": {
"self": "https://api.ssodnet.obspm.fr/quaero/1/sso/Mars/resolver?epoch=2457772.0749884"
}
},
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [23.558179798130066,-3.500094251546666,1.7585274746630883]
}
}
Returns a collection of relevant solar system objects matching a specified query. This method is intended to provide a full search capability on all fields of the Sso. It can be used for advanced queries and the query string follows the query DSL syntax ref..
GET /sso/search
q (string, required) Query string (URL-encoded).
offset (integer, optional, default 0) Offsets the start of each page by the number specified.
limit (integer, optional, default 10) Number of Sso that are returned in each page.
Collection of Sso object.
400 Bad Request
502 Something went wrong on SsODNet's end.
Provides search as you type facility on solar system objects. It is intended to be used in an autocomplete search box. The search matches only against name and aliases fields of the Sso.
It is also possible to search for Sso amongst multiple types of Sso using type parameters and to search for Sso with ephemeris available using the ephemeris parameters.
GET /sso/instant-search
q (string, required) Token or partial token of the name or aliases (URL-encoded).
limit (integer, optional, default 10) Number of Sso that are returned.
type (string, optional) The type of the Sso (case sensitive).
ephemeris (value-less, optional) If present returns only Sso with ephemeris available.
Collection of Sso resources.
400 Bad Request
502 Something went wrong on SsODNet's end.
Returns current values of type and class fields that can be found in SsODNet. Use this method to get an up to date list of types and classes of Sso.
OPTIONS /sso
types The list of available types.
classes The list of existing classes.
502 Something went wrong on SsODNet's end.
OPTIONS /sso
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
"classes": ["MB","Middle","Inner","Outer","NEA","Mars-Crosser"...],
"types": ["Asteroid","Comet","Exoplanet","Satellite","Planet","Dwarf Planet"...]
}
Returns the current status of the Quaero API. Use this method to verify the availability of the Quaero API.
GET /status
204 Quaero API is operating normally.
5xx Something went wrong on SsODNet's end. Quaero is currently unavailable.