SsODNet

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"],
  "system":"Mars",
  "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.

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:

https://api.ssodnet.imcce.fr/quaero/1/sso?q=<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:

• ?q=io&type=Asteroid retrieves all the asteroids named Io
• ?q=Schwassmann-Wachmann&type=Comet retrieves all the comets named Schwassmann-Wachmann

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:

https://api.ssodnet.imcce.fr/quaero/1/sso/<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>):

• /sso/Io_(Asteroid) retrieves the sheet of the asteroid Io
• /sso/Io_(Satellite) retrieves the sheet of the satellite Io

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 (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.

Term

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":

• ?q=ceres pallas vesta retrieves the sheets of Ceres, Pallas and Vesta
• ?q="Schwassmann Wachmann" retrieves the sheets of all objects named Schwassmann-Wachmann

Operators

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
• ?q=linear AND 2006 retrieves the sheets of the comets LINEAR also named C/2006 xxx
• ?q=linear AND (2006 OR 2007) retrieves the sheets of the comets LINEAR also named C/2006 xxx and C/2007 xxx

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:

• ?q=type:"Dwarf Planet" retrieves the sheets of all Dwarf planets
• ?q=system:(Earth OR Mars) retrieves the sheets of all objects which belong to the planetary systems of the Earth and Mars
• ?q=class:(Classical AND Inner) AND 2006 retrieves the sheets of all the KBO of the Inner Classical belt which name contains 2006
• ?q=type:Exoplanet AND name:kepler retrieves the sheets of all the exoplanets named Kepler

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"

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:

https://api.ssodnet.imcce.fr/quaero/1/{sso-id}/resolver

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

• /sso/Ceres/resolver

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:

• /sso/Ceres/resolver?epoch=2457754.5

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

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.

SsODNet autocomplete testbed: View source code (standalone demo)

<!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 rel="stylesheet" type="text/css" href="/webservices/css/autocomplete.css">
   <link rel="stylesheet" type="text/css" href="/webservices/css/index.css">
</head>
<body>
   <h1>SsODNet-Quaero autocomplete demo</h1>
   <input id="autocomplete-quaero" type="text" size="64" maxlength="450" value="" placeholder="Enter first letters of a Sso name (e.g. cer)" data-autocomplete-no-result="No result" data-autocomplete-param-name="q"/>
   <div class="clearfix"></div>
   <div class="autocomplete"></div>

   <script src="/webservices/js/autocomplete.js"></script>
   <script>
     // Override autocomplete.js defaults
     AutoComplete({
        EmptyMessage: "No item found",
        MinChars: 1,
        Url: 'https://api.ssodnet.imcce.fr/quaero/1/sso/instant-search',
        QueryArg: "q",
        _Post: function (response) {
          try {
            var returnResponse = [];
            //JSON return
            var json = JSON.parse(response);
            // Parse Quaero server response
            var rdata = json.data;
            for (var i=0; i<rdata.length; i++) {
                var otype = (rdata[i].type) ? rdata[i].type : "?";
                var oclass = "";
                if (rdata[i].class) {
                  oclass = rdata[i].class[0];
                  for (var j=1; j<rdata[i].class.length; j++) { oclass += '>' + rdata[i].class[j]; }
                }
                // Type and class of object
                var obj = ' (' + otype + ' ' + oclass + ')';
                var prefix = otype.charAt(0).toLowerCase() + ':';
                returnResponse[returnResponse.length] = { "Value": prefix+rdata[i].name, "Label": this._Highlight(rdata[i].name+obj) };
            }
            return returnResponse;
          } catch (event) {
            //HTML return
            return response;
          }
        }
     }, "#autocomplete-quaero");
   </script>
</body>
</html>

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:

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

SsODNet types and classes of Sso: View source code

<script>
var getTypesAndClasses = document.querySelector('#ssodnet-types-and-classes');
getTypesAndClasses.onclick = function () {
  var res = document.getElementById("sso_types_and_classes");
  var xhr = new XMLHttpRequest();
  xhr.open('OPTIONS', "https://api.ssodnet.imcce.fr/quaero/1/sso", true);
  xhr.send();
  xhr.onreadystatechange = function () {
    if (xhr.readyState == 4 && xhr.status == 200) {
      var resp = JSON.parse(xhr.responseText);
      var types = JSON.stringify(resp.types, undefined, '   ');
      var classes = JSON.stringify(resp.classes, undefined, '   ');
      res.innerText = "Types = " + types + "\n\nClasses = " + classes;
    }
  }
};
</script>

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."