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:
- http://vo.imcce.fr/webservices/ssodnet/resolver.php?[parameters]
where
[parameters] is a list of parameters separated by the character &.
The allowed parameters are:
| Parameter | Definition | Limits |
| -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 |
- See the How to name object section of the SsODNet documentation for a full description.
- Optional parameter. If mime is omitted, then the output is formatted as VOTable.
- Optional parameter. If epoch is omitted, then the coordinates are computed for epoch 'now'.
- Optional parameter. If maxrec is omitted, then the first ten resolved Sso are retrieved (equivalent to maxrec=10).
- Optional parameter. If ephem is omitted, then the ephemeris are not computed (Default is false).
- 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:
- http://vo.imcce.fr/webservices/ssodnet/ssodnet.php
- Namespace:
- http://vo.imcce.fr/webservices/ssodnet
- WSDL:
- http://vo.imcce.fr/webservices/ssodnet/ssodnet.php?wsdl
- SOAP header:
- name of the SOAP header element: 'clientID'
- SOAP header's content: array('from' => 'YourName', 'hostip'=>'')
- Method:
- resolver (inputArray)
The input parameters of the method is an array which
must contained the following parameters:
| Variable | Type | Units | Limits or values | Default | Comment |
| 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 |
- 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'
- 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
- 'status'
- the HTTP status-code of the response (e.g. 400: bad request, 404: not found, 500: internal error)
- 'ticket'
- the Unix timestamp of the answer which can be useful to stamp the request
- 'result'
- a formatted (VOTable, JSON, or 'pipe' separated string) containing the information about each resolved Sso:
| No. | Name | Definition |
| 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) |
- Unique identifier of the Sso into SsODNet/Quaero database
- Object types are: Asteroid, Comet, Dwarf Planet, Exoplanet, Planet, Satellite, Spacecraft, Spacejunk
- See Sso classes in Skybot documentation
Depending on the selected result type, the output is formatted as:
- votable
- the data are written in the IVOA standard VOTable format
- html
- the data are transformed in a HTML document using a XSLT processing (SsODNet resolver XSL style sheet)
- json
- the data are written in the JSON data-interchange format
- text
- 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:
- mime=text
- mime=json
- mime=html
- mime=votable
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>"
or
#> 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';
// SsODNet WSDL
$uriwsdl = $namespace.'/ssodnet.wsdl';
3/ Create a SoapClient object in WSDL mode, set the SOAP header, then call the method and catch exceptions:
try
{
// 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;
}
else
{
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);
}
