The Solar system Open Database Network
.: Quaero :.
< SsODNet REST API />
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.
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link type="text/css" rel="stylesheet" href="//code.jquery.com/ui/1.9.2/themes/base/jquery-ui.css"/>
<style type="text/css">
/* Overload the jquery-ui CSS */
.ui-widget { font-family: Verdana,Arial,sans-serif; cursor: pointer; }
.ui-widget-content { border: 2px solid #dddddd; background: #f6f7f9; }
.ui-widget-content .ui-state-focus { border: 1px solid #cdcdcd; background: #fff; color: blue; }
</style>
<script src="//code.jquery.com/jquery-1.8.3.js"></script>
<script src="//code.jquery.com/ui/1.9.2/jquery-ui.js"></script>
<script src="//vo.imcce.fr/webservices/share/ssodnet-autocomplete.js"></script>
<script>
$(function() { $("#q").ssodnetautocomplete(); });
</script>
</head>
<body>
<div class="ui-widget">
<label for="q">SsODNet autocomplete testbed: </label>
<input id="q" name="q" type="text" maxlength="450" value="" placeholder="Enter Sso name"/>
</div>
</body>
</html>
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
<script>
$(function() {
$("#sso_types_and_classes").hide();
/* Lists of types and classes of Sso */
$("#ssodnet_types_and_classes").click(function(){
$.ajax({
url: "https://api.ssodnet.imcce.fr/quaero/1/sso",
type: 'OPTIONS',
dataType: 'json',
success: function(resp, status, xhr) {
var t = JSON.stringify(resp.types);
var c = JSON.stringify(resp.classes);
var r = "Types:<br/>" + t + "<br/>" + "Classes:<br/>" + c;
$('#sso_types_and_classes').html(r);
},
error: function(xhr, status, exception) {
$('#sso_types_and_classes').html('Something went wrong!');
}
});
$("#sso_types_and_classes").show();
});
});
</script>
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."