Logo IMCCE-VOParis

Observatoire de Paris / CNRS

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

The Solar system Open Database Network

.: resolver :.

.: Purpose

This method is intended to people who need to resolve the name of a solar system object (asteroid, dwarf-planet, planet, natural satellite, comet, spacecraft or spacejunk) into celestial coordinates. It is a high level service dedicated to normal users. Developers may prefer the low level Quaero REST API.

.: HTTP Request

The SsODNet Resolver service can be accessed using the SsODNet query forms. If you are a software/solutions developer, you might want to include the SsODNet Resolver service into your application. This can be done by using the web service method or by using the following HTTP request:
where [parameters] is a list of parameters separated by the character &. The allowed parameters are:
-name=<string> The designation of the target (1) Ex.: 2, Pallas, 1999_TC36, p/halley
-mime=<string> Mime type of the results (1,2) (votable) | html | json | text
-epoch=<string> Requested epoch, expressed in Julian day, ISO format,
or formatted as any English textual datetime (1,3)
years 1000.0 to 3000.0, default is now
-maxrec=<n> Maximum number of Sso to retrieve (1,4) n ≥ 1, default is 10
-ephem=<int> To request (=1) or not (=0) the equatorial coordinates
of the target at epoch (1,5)
1 or 0, default is 0
-coord=<string> To request 2D equatorial coordinates (RA,DEC), or 3D ones (RA,DEC,Dobs)
where Dobs is the distance to the observer (1,6)
2D or 3D, default is 2D
  1. See the How to name object section of the SsODNet documentation for a full description.
  2. Optional parameter. If mime is omitted, then the output is formatted as VOTable.
  3. Optional parameter. If epoch is omitted, then the coordinates are computed for epoch 'now'.
  4. Optional parameter. If maxrec is omitted, then the first ten resolved Sso are retrieved (equivalent to maxrec=10).
  5. Optional parameter. If ephem is omitted, then the ephemeris are not computed (Default is false).
  6. Optional parameter. If coord is omitted, then 2D coordinates are provided (Default is 2D).

The output parameters are described in the following table and are available in VOTable, HTML, JSON or plain text format (cf. examples). The -mime, -epoch, -maxrec and -ephem parameters are optionnal, and can be omitted. In that case, the response is sent in VOTable format, the epoch is 'now', the first ten resolved targets are retrieved (maxrec=10), and their ephemerides are not computed (ephem=0). The other inputs are mandatory.

.: Web service

The SsODNet Web service provides methods based on SOAP and HTTP POST verb which allow one to interact between its own application and the SsODNet service. Here is the useful information to invoke the SsODNet resolver method:
Web Service URI:
SOAP header:
name of the SOAP header element: 'clientID'
SOAP header's content: array('from' => 'YourName', 'hostip'=>'')
resolver  (inputArray)
- The input parameters of the method is an array which must contained the following parameters:
VariableTypeUnitsLimits or valuesDefaultComment
name string Designation - none Name or designation or number of the target (1)
mime string - votable | html | json | text votable Mime type of the results
epoch string - 2086308.0 .. 2816788.0
(1000-01-01 12h .. 3000-01-01 12h)
none Requested epoch, expressed in Julian day, ISO format,
or formatted as any English textual datetime (1)
maxrec int - ≥ 1 10 Maximum number of Sso to retrieve.
ephem int - 1 | 0 0 Boolean to request (=1) or not (=0) the celestial coordinates of the target at epoch
coord string - 2D | 3D 2D To request 2D equatorial coordinates (RA,DEC), or 3D ones (RA,DEC,Dobs)
where Dobs is the distance to the observer
  1. See the HOWTO section of the SsODNet documentation for a full description.
- The output parameters of the method is an object, named output, containing the following attributes:
flag=1 means that one or more Sso has been found
flag=0 means that no Sso has been found
flag=-1 means that an error occured
the HTTP status-code of the response (e.g. 400: bad request, 404: not found, 500: internal error)
the Unix timestamp of the answer which can be useful to stamp the request
a formatted (VOTable, JSON, or 'pipe' separated string) containing the information about each resolved Sso:
1 id Id of the Sso (1)
2 type Type of the Sso (2)
3 class Class of the Sso (3)
4 name Official or usual name of the Sso
5 number Official or usual number of the Sso, null if the object is unnumbered
6 aliases Comma separated list of all the aliases of the Sso
7 parent Id of the parent of the Sso (1)
8 system Name of the planetary system to which the Sso belongs
9 epoch Epoch of the ephemeris (Julian day, UTC), if requested (-ephem=1)
10 ra Geocentric astrometric J2000 right ascension of the Sso in degrees, if requested (-ephem=1)
11 dec Geocentric astrometric J2000 declination of the Sso (degrees), if requested (-ephem=1)
12 Dobs Distance to the observer (AU), if requested (=ephem=1&-coord=3D)
13 referenceFrame Reference plane of the ephemerides (equatorial), if requested (=ephem=1)
  1. Unique identifier of the Sso into SsODNet/Quaero database
  2. Object types are: Asteroid, Comet, Dwarf Planet, Exoplanet, Planet, Satellite, Spacecraft, Spacejunk
  3. See Sso classes in Skybot documentation
- Depending on the selected result type, the output is formatted as:
the data are written in the IVOA standard VOTable format
the data are transformed in a HTML document using a XSLT processing (SsODNet resolver XSL style sheet)
the data are written in the JSON data-interchange format
the data are returned in plain text where each block of data is separated by the semi-colon character ';' and each value in a block is separated by the pipe '|' character
- Examples: click on the following links to get the result for -name=io, -epoch=now, -maxrec=5, -ephem=1, -coord=2D and:

.: How to consume:

You have two ways to use the SsODNet web service: by writting a client to send requests to the SsODNet server and to receive and analyze the response, or by using a command line interface and a data transfert program such as curl or wget. For that, just execute one of the following commands in a console:

#> curl "<URL>"
#> wget "<URL>"

where <URL> is described in section HTTP request. In order to help you to invoke the SsODNet web service, we provide some clients written in differents languages. Here are some detailed explanations to see how to write a client with PHP and SOAP which invokes the getavailability method:

1/ Provide the input parameters which are mandatory for the service:

// Client's ID: provide the name of your project or organisation or yourself
$from = 'MyDemo';
// Input parameters
$param = array(
    'name'=> 'io',
    'mime' => 'votable',
    'epoch' => 'now',
    'maxrec' => 10,
    'ephem' => 1,
    'coord' => '2D'

2/ Define the SOAP options, the namespace and the WSDL URI of SsODNet web service:

// Enables or disables the WSDL caching feature
ini_set('soap.wsdl_cache_enabled', 1);
// SsODNet namespace
$namespace = 'http://vo.imcce.fr/webservices/ssodnet';
$uriwsdl = $namespace.'/ssodnet.wsdl';

3/ Create a SoapClient object in WSDL mode, set the SOAP header, then call the method and catch exceptions:

  // Constructs the client
  $client = new SoapClient($uriwsdl, array('exceptions'=>1));
  // SOAP header
  $header = array('from'=>$from, 'hostip'=>'');
  $client->__setSoapHeaders(array(new SOAPHeader($namespace, 'clientID', $header)));
  // Call the resolver method
  $response = $client->__soapCall('resolver',array($param));
  // Display the results
  if ($param['mime'] == 'text')
    $res = explode(';', $response->output);
    $nbr = count($res);
    $newkey = array_keys($res);
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: text/plain");
    for ($i=0; $i<$nbr; $i++) { echo trim($res[$newkey[$i]]),"\n"; };
  else if ($param['mime'] == 'json')
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: application/json");
    echo $response->output;
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: text/xml;content=x-votable");
    echo $response->output."\n";
catch (SoapFault $fault)
  trigger_error("SOAP Fault: {$fault->getTraceAsString()} (faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring})", E_USER_ERROR);