Low-level Name resolver

quaero is a REST API for people who need to identify the name of a planetary object (asteroid, dwarf-planet, planet, natural satellite, comet, space probes and junks, exoplanets), and to resolve it in its sky coordinates. It is a low-level API dedicated to developers. Normal users may prefer the high-level resolver API.

The core of SsODNet is composed of a full-text search engine, powered by Elasticsearch, which provides a fast search mechanism to identify and to explore the naming of objects: you submit a name, or a pattern of name, of any object, and in return you receive the list of the corresponding bodies, their known aliases, and much more information composing the identity of the body.

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 the planetary objects which match the requested name or pattern.

Example: GET /sso/Mars

GET /sso/Mars

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

  "id": "Mars",
  "name": "Mars",
  "aliases": ["4","499"],
  "parent": "Sun",
  "type": "Planet",
  "physical-ephemeris": true,
  "physical-models": [1],
  "ephemeris": true,
  "updated": "2019-11-25"

If the query does not match any object, then a "Not found" resource is returned:

  "status": "404 Not Found",
  "note": "Not Found"

Read the Quaero REST API documention for detailed information about quaero and its usage (for developers).

Quaero's API is designed to provide an easy to use and fast tool to search for planetary objects (sso and search methods), to resolve their names (resolver method), or to be used as an autocompletion mechanism for names (instant search method) into Web forms and applications connected to the Internet.

Search by name

To get the object matching a given name, you have to send a HTTP GET request on the sso end-point of Quaero's service:<pattern>

The query pattern (parameter q) is mandatory, and contains the name, or a pattern, of the requested object, given as a full or partial name. It is case insensitive, must be URL-encoded, and it must not contain any wildcard. The response provides all the objects which contain the exact word 'pattern' into their name or alias:

  • ?q=io retrieves all the object with Io into their name or alias
  • ?q=P/Schwassmann-Wachmann retrieves all the object with P/Schwassmann-Wachmann into their name or alias
  • ?q=2010 retrieves all the object with 2010 into their name or alias

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

The list of known types (case sensitive) is detailed below.

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

  • limit (integer) to limit the number of objects 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 an object, which corresponds to its id in Quaero resource, you can access directly to its record sheet by sending the following HTTP GET request:<id>

where id must be the exact name (case sensitive) of the requested target:

  • /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 objects (e.g. Io, Europa, ...), the object type must be appended to the name into brackets, e.g. id = <name>_(<type>):

Quaero lets you build complex queries through HTTP GET requests on the search end-point of the service:<predicat>

The query string (parameter q) 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. Read also the Query string syntax documentation for a full review of the query string “mini-language” used by the q parameter.


A term allows to search for all the words in the same order. It can be a single word, e.g. ceres or 73p, or a phrase, surrounded by double quotes, e.g. "Schwassmann Wachmann":


Operators allow 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:

Field names

Field names allow 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, ...

Wildcards, regular expressions and fuzziness can be embedded in the query string to match a term to a pattern, or to search for similar terms. 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 objects which name starts with "ura"
  • regular expression: ?q=name:/cer..../ retrieves the sheets of all objects which name starts with "cer" followed by 4 letters
  • fuzziness: ?q=cre~ retrieves the sheets of all objects which name is similar to "cre"

Name resolver

In complement to the information provided by Quaero, the sky coordinates of a given object can be obtained, if its dynamical properties are known, through the dedicated end-point:{sso-id}/resolver

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

The response is sent back in GeoJSON format (Content-Type: application/geo+json), and contains the J2000 astrometric geocentric equatorial coordinates of the object: 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 objects are only available if the field ephemeris is set to true. If not, Quaero returns the HTTP code 501 ("Not Implemented"). The optional parameter epoch (Julian day) can be used to retrieve the ephemeris at any epoch in the period 973-06-04 12h (2076601.0) to 3026-07-25 12h (2826489.0). The timescale is UTC:

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

Autocomplete facility

Quaero can be used to create an autocomplete widget for a Web forms, offering suggestions of names while the user types into an input field. The following testbed shows how it works. It uses the autocomplete-js library, a fast and lightweight autocomplete library without any dependency. To implement the autocomplete functionnality into a Web page, download the library, and be inspired by the source code.

(standalone demo)

type and class fields

The lists of types and classes of objects known by SsODNet can be obtained through a custom HTTP request (OPTIONS method) to be sent to the sso end-point of Quaero API:



If you implement the SsODNet.quaero service into your application, an acknowledgment shuch as the following would be appreciated:

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