Skybot 3D
.: getSso :.
Purpose
This method is intended to people who want to retrieve in one request the state vectors of planets
(and their major satellites), comets and asteroids at a reference epoch. The state vectors are those
provided by the methods
getPlanet,
getComet and
getAster respectively.
HTTP Request
The Skybot3D getSso service can be accessed using the
Skybot3D query forms (TBD).
If you are a software/solutions developer, you might want to include the Skybot3D getSso 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/skybot3d/getSso_query.php?[parameters]
Parameter | Definition | Limits |
-ep=<string> |
Epoch requested, expressed in Julian day or formatted as any English textual datetime. Default to now. |
2411320.0 .. 2473530.0 1889-11-13 12h .. 2060-03-21 12h |
-mime=<string> |
Mime type of the results (default to VOTable) |
votable | html | text | json |
-coord=<string> |
Type of coordinates: rectangular for (x,y,z) coordinates, spherical for RA and DEC |
rectangular (default) | spherical |
-getFile=<0|1> |
Active only with mime types VOTable and text.
Be aware that the amount of data to receive can be large (tens of Megabytes).
For more info, read below.
|
0 (default) | 1
|
-from=<string> |
Word which definite the name of the caller application, or which describes the request |
any short string (without space) |
The output is described in the following table and is available in
VOTable, HTML, JSon or plain text format
(cf. examples). The -mime parameter is optionnal and its value can be
omitted (just write nothing or &-mime= without value). In this case, the output is formatted
in VOTable. The other input parameters can also be omitted: in that case, the query requests
the rectangular ephemeris at epoch 'now' of all solar system objects (planets and their major satellites,
comets and asteroids).
Web service
The Skybot3D Web service provides methods based on
SOAP and
HTTP POST verb which allow
one to interact between its own application and the Skybot3D service. Here is the useful information to
invoke the getSso method:
- Web Service URI:
- http://vo.imcce.fr/webservices/skybot3d/skybot3d.php
- Namespace:
- http://vo.imcce.fr/webservices/skybot3d
- WSDL:
- http://vo.imcce.fr/webservices/skybot3d/skybot3d.php?wsdl
- SOAP header:
- name of the SOAP header element: 'clientID'
- SOAP header's content: array('from' => 'YourName', 'hostip'=>'')
- Method:
- getSso (inputArray)
The input parameters of the method is an array
which must contained the following parameters:
Variable | Type | Units | Limits or values | Default | Comment |
epoch |
string |
- |
2411320.0 .. 2473540.0 (1889-11-13 12h .. 2060-03-21 12h) |
none |
Requested epoch, expressed in Julian day, ISO format or formatted as any English textual datetime |
class |
string |
- |
Not used |
empty |
All objects are retrieved. Use one of the specific methods to filter out classes of objects. |
limit |
integer |
- |
Not used |
0 |
All objects are retrieved. Use one of the specific methods to filter out the number of objects. |
coord |
string |
- |
rectangular | spherical |
rectangular |
Requested type of coordinates of the targets: x,y,z or RA,DEC |
mime |
string |
- |
votable | html | text | json |
votable |
Mime type of the results |
The output of the method does not directly provide the
ephemeris of objects. Instead it provides an object which contains the information needed to access the data:
- 'flag'
- the status of the response: flag=1 means ok; flag=0 means that no body has been found; flag=-1 means that an error occured
- 'ticket'
- the Unix timestamp of the answer which can be useful to stamp the request
- 'nbast'
- the number of asteroids contained in the result file
- 'refdate'
- the epoch of the ephemeris, in julian day
- 'filename'
- the URL of a Bzipped file which contains the VOtable document (extension .xml.bz2),
or the URL of a ZIP file which contains three data
files in plain text format (extension .zip).
- 'filesize'
- the size of the result file, in bytes
To get the result file, use a network downloader, such as wget or curl, or download the file by using
your preferred Web browser. You will need to (b)unzip the file to read it with any text editor.
Depending on the selected mime 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 (Skybot3D XSL style sheet)
- text
- the data are returned in plain text (CSV-like) with one line of data per object. The three files have a different number
of columns depending on the type of objects (planets, comets, asteroids).
- json
- the data are returned in the JSON (JavaScript Object Notation) data-interchange format
For each type of objects, specific parameters are provided.
See the methods getPlanet, getComet and getAster
for detailed information about the output parameters.
Examples: click on the following links to get the state vectors of
the solar system objects and:
- mime=text
- mime=json
- mime=html
- mime=votable
How to consume:
In order to help you to invoke the Skybot3D 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
getSso
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 = 'MyName';
// Input parameters
$param = array(
'epoch' => "now",
'class' => "",
'limit' => 0,
'coord' => "rectangular",
'mime' => "html"
);
2/ Define the SOAP options, the namespace and the WSDL URI of Skybot3D web service:
// Enables or disables the WSDL caching feature
ini_set('soap.wsdl_cache_enabled', 1);
// Skybot3D namespace
$namespace = 'http://vo.imcce.fr/webservices/skybot3d';
// Skybot3D WSDL
$uriwsdl = $namespace.'/skybot3d.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('getSso',array($param));
// Display the results
if ($param['mime'] == 'text')
{
header("Content-Type: text/plain");
if ($response->flag > 0) {
echo "# Flag : ".$response->flag."\n";
echo "# Ticket : ".$response->ticket."\n";
echo "# nbSso : ".$response->nbsso."\n";
echo "# refDate : ".$response->refdate."\n";
echo "# fileName : ".$response->file."\n";
echo "# fileSize : ".$response->size." bytes\n";
} else {
echo "# Flag : ".$response->flag."\n";
echo "# Ticket : ".$response->ticket."\n";
echo "# Message : ".$response->result."\n";
}
else if ($param['mime'] == 'json')
{
header("Content-Type: application/json");
if ($response->flag > 0) {
echo $response->result."\n";
} else {
echo "# Flag : ".$response->flag."\n";
echo "# Ticket : ".$response->ticket."\n";
echo "# Message : ".$response->result."\n";
}
}
else
{
header("Content-Type: text/xml;content=x-votable");
echo $response->result."\n";
}
}
catch (SoapFault $fault)
{
trigger_error("SOAP Fault: {$fault->getTraceAsString()} (faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring})", E_USER_ERROR);
}