Logo IMCCE-VOParis

THE IMCCE VIRTUAL OBSERVATORY
SOLAR SYSTEM PORTAL
Observatoire de Paris / CNRS

Logo IMCCE
Portal Home Page | Report issue | Legal notice | Contact us

The Solar system Open Database Network

.: Quaero :.

< SsODNet REST API />

Current version: Quaero 1

> Purpose

The core of SsODNet is composed of a full-text search engine, powered by Elasticsearch, which provides a fast search mechanism to seek for and discover solar system object (Sso): you submit a name, or a pattern of name, of any solar system object, and in return you receive the list of the corresponding Sso, their known aliases, and much more information. Quaero is designed to provide an easy to use and fast tool to search for solar system objects (sso and search methods), to resolve their names (resolver method), or to be used as an autocompletion mechanism for Sso names (instant search method) into Web forms and applications connected to the Internet.

The response to a query is composed of a standard HTTP code (mainly 200 for success, 400 for bad request, 404 for not found, and 500 for internal error), and a JSON-formatted list of all Sso which match the requested name or pattern.
Example:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{ "total": 1, "data": [ 
    { "links": {"self": "https://api.ssodnet.imcce.fr/quaero/1/sso/Mars"}, "system": "Mars", "ephemeris": true,
      "id": "Mars", "parent": "Sun", "type": "Planet", "name": "Mars", "aliases": ["4"] } 
] }
If the query does not match any Sso, then an empty Sso resource is returned:
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{ "total": 0, "data": [ ] }

Read the Quaero REST API documention for detailed information about Quaero (for developers).

> Search by name

To get the Sso matching a given name, you have to send a HTTP GET request on the sso end-point of Quaero's service:
https://api.ssodnet.imcce.fr/quaero/1/sso?q=<pattern>
The query string (q parameter) is mandatory, and contains the name, or a pattern, of the requested Sso, given as a full or partial name. It is case insensitive, must be URL-encoded, and it must not contain any wildcard. The response will provide all the Sso which contain the exact word 'pattern'. For example:
  • ?q=io retrieves all the Sso with name Io.
  • ?q=P/Schwassmann-Wachmann retrieves all the Sso with P/Schwassmann-Wachmann into their name.
  • ?q=2010 retrieves all the Sso with 2010 into their name.

To limit the query to a given type of Sso (e.g. asteroid or comet or ...), add the parameter type (case sensitive) to the query:

The list of known types is detailed below.

Two other optional parameters can be used to control the response:

  • * limit (integer) to limit the number of Sso sent back (default 10)
  • * offset (integer) to shift the starting page of the response by the specified number (default 0)

If you know the exact name of a Sso, which corresponds to its id in Quaero resource, you can access directly to its record sheet by sending the following HTTP GET request:

https://api.ssodnet.imcce.fr/quaero/1/sso/<id>
where id must be the exact name (case sensitive) of the requested Sso.
Example:
  • /sso/Ceres retrieves the sheet of the dwarf planet Ceres (id=Ceres).
  • /sso/2015_BA307 retrieves the sheet of the asteroid 2015 BA307 (id=2015_BA307).
  • /sso/73P retrieves the sheet of the comet P/Schwassmann-Wachmann 3 (id=73P).

If an exact word refers to multiple Sso (e.g. Io, Europa, ...), the Sso type must be appended to the name into brackets, e.g. id = <name>_(<type>).
Examples:

> Extended search

Quaero lets you build complex queries through HTTP GET requests on the search end-point of the service:
https://api.ssodnet.imcce.fr/quaero/1/sso/search?q=<predicat>

The query string (q parameter) must follow the standard Lucene Query Syntax. It is parsed into a series of field names, terms and operators. Like the sso method, the search method accepts the optional parameters limit and offset to control the response.

* A term can be a single word, e.g. ceres or 73p, or a phrase, surrounded by double quotes, e.g. "Schwassmann Wachmann", which searches for all the words in the phrase, in the same order.
Examples:

* Operators allow you to customize the search. The default operator is OR, which means that the query ceres pallas is translated to ceres OR pallas. The familiar operators are AND, OR and NOT. NOT takes precedence over AND, which takes precedence over OR. Other operators are + (this term must be present) and - (this term must not be present). While the AND and OR can affect the terms to the left and right, the + and - only affect the term to the right of the operator. Multiple terms or clauses can be grouped together with parentheses to control the logic of the query.
Examples:

* Field names allow you to refine the search on the selected information available in Quareo response. Each field can be used as the prefix of a term in the query, e.g. field:term. If no prefix field is specified then the query is on the fields name and aliases.
Examples:

The current list of field names is: name, id, ephemeris, aliases, system, parent, type, class.

* Wildcards, regular expressions, fuzziness, ... can be embedded in the query string to match a term to a pattern, to search for similar terms, etc. It must be used with caution because such query can be particularly heavy, e.g. ?q=*es implies that all terms in the name and aliases indexes have to be examined. Read the Query string syntax documentation for more information about these operators.
Examples:

  • - wildcard: ?q=ura* retrieves the sheets of all Sso which name starts with "ura".
  • - regular expression: ?q=name:/cer..../ retrieves the sheets of all the Sso which name starts with "cer" followed by 4 letters.
  • - fuzziness: ?q=cre~ retrieves the sheets of all the Sso which name is similar to "cre".

Read the Query string syntax documentation for a full review of the query string “mini-language” used by the q parameter.

> Sso name resolver

In complement to the information provided by Quaero, the actual position on the celestial sphere of a given Sso can be obtained throught the dedicated end-point:
https://api.ssodnet.imcce.fr/quaero/1/{sso-id}/resolver

where {sso-id} is the (unique) ID of the Sso, available in each sheet under the field named id.
Example:

The response is sent back in GeoJSON format (Content-Type: application/geo+json), and contains the J2000 astrometric geocentric equatorial coordinates of the Sso: right ascension (in hours), declination (in degrees), and the distance to the observer (in au). The UTC epoch of the coordinates is reminded into the properties of the GEOJson object, as well as a raw definition of the reference system of the coordinates. Ephemerides of Sso are only available if the field ephemeris of the Sso is set to true. If it is not the case, Quaero returns the HTTP code 501 ("Not Implemented"). The optional parameter epoch (Julian day) can be used to retrieve the ephemerides of Sso at any epoch in the period -3000-02-23 0h to 3000-05-06 0h.
Example:

Read the Quaero REST API documention for a description of the objects returned by the resolver.

> Autocomplete facility

You can use Quaero to create an autocomplete widget for your Web forms, offering suggestions of names of Sso while the user types into an input field. The following code source provides a simple way to implement it by using our ssodnet-autocomplete Javascript implementation, which is based on the JQuery autocomplete widget.
  View code source  

> Available values for type and class fields

The lists of types and classes of Sso known by SsODNet can be obtained throught a custom HTTP request (OPTIONS method) to be sent to the sso end-point of Quaero's service, e.g.:

curl -X OPTIONS https://api.ssodnet.imcce.fr/quaero/1/sso

  View code source  


    

 

> Credit

If you implement the Quaero/SsODNet API into your application, the following acknowledgment would be appreciated:

   "The Sso name search is powered by IMCCE's SsODNet/Quaero REST API."