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
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.
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:
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
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:
?q=linear -2001 -2002 retrieves the sheets of the comets LINEAR except those named C/2001 xxx and C/2002 xxx
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.
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.
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"
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:
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:
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.