vOs⁴OVirtual Observatory Solar System Scaling Service for Outreach

API - Web Service

About

The API (application programming interface) allows to query directly VOS⁴O from your own software. You can use it to create your own Web page to scale the solar system, or script the queries and retrieve the table and images generated. Two methods are available to query the service:

• HTTP request : simply query the service through a non-interactive Internet download software such as wget, curl or a Javascript object XMLHttpRequest..
• Web Service : query the servive through its Web Service (WS) based on SOAP+WSDL+HTTP protocols.

Using the API is free (as in freedom) and free of charge for any non-profit usage (personal or educational). We highly recommand to contact us if you develop an application using VOS⁴O service to receive informations on updates.

Please use our bug tracker to report any bug or request new functionalities.

Definition of the scale

There are three ways to define the scale :

x:y

to define a multiplying coefficient X/Y to apply to every single length. For instance, the scale 1:1000000 (a millionth) will divide by one million all the planet distances and diameters.

a(planet):x

to set the scale such as the distance of the planet equals x. For instance, if the parameters unit=m (meter), then the scale a(neptune):7.22 will create a view of the solar system in which the distance Sun – Neptune is 7.22 metres.

d(planet):x

to set the scale such as the diameter of the planet equals x. For instance, if the parameter unit=m (metre), then the scale d(earth):1 will draw a solar system in which the diameter of the Earth equals 1 meter.

Description of the output table and images

The output table generated by VOS⁴O lists the diameter of the Sun and the planets and the distance between the planets and the Sun, set to the chosen scale. The orbital eccentricity of the planets, and their mean heliocentric longitudes (in degrees) at the requested epoch, are also reported.

The first image generated by VOS⁴O represents the solar system set to scale, according to the defined parameters. The planets are drawn along an axis in logarithmic scale at their correct relative distance. Next to each, it diameter and distance to the Sun (set to scale) are reported.

The second image represent the solar system as seen from above. Each planet is located on its orbit at its mean heliocentric longitude, computed at the requested epoch. The reference for the longitudes is the mean vernal point (or mean equinox), represented by the γ symbol.

HTTP request

With a non-interactive Internet software such as wget, curl, or with an Internet browser, call the service through its HTTP access point

https://ssp.imcce.fr/webservices/vos4o/scale.php?[parameters]

in which [parameters] is a list of parameters (defined in table 1) separated by the & symbol. If not any parameter is set, the service sets the solar system with the default values listed in table 1.

^* If the MIME type is VOTABLE, the autoscale parameter is set to 0 regardless to its value.

The result of a HTTP request consists in a table and two images, formated in HTML, VOTable/XML or simple text accordingly to the specified MIME type (-mime parameter).

Examples of requests :

• The solar system to scale 1:1000000 (one millionth).
• The solar system such as the the distance Sun - Neptune is 7.22 meters.
• The solar systen such as the diameter of the Earth equals meter.

Web service

The VOS⁴O service can be queried through a Web Service based on the SOAP+WSDL+HTTP protocoles allowing for a direct interaction between your own application and the service.

Web Service URI :

https://ssp.imcce.fr/webservices/vos4o/vos4o.php

Namespace :

https://ssp.imcce.fr/webservices/vos4o

WSDL:

https://ssp.imcce.fr/webservices/vos4o/vos4o.php?wsdl

SOAP header:

Name of the SOAP header : clientID

SOAP header : array('from' => 'NomProjet', 'hostip'=>'')

Method :

scale (inputArray)

Input parameters

The input parameters of the scale methods are grouped in a table and must define the variables described in table 2.

^* If the MIME type is VOTABLE then the autoscale parameter is forced to false regardless its value.

Output parameters

The results of the 'scale' method is an object with the following attributes :

'status'

status of the answer, based on HTTP codes : 200 = ok, 400 = bad request, 404 = not found, 500 = internal error.

'ticket'

Timestamp of the answer.

'result'

A string containing the result table and the images of the solar system set to scale.

MIME type

According to the selected MIME type, the answer is provided in the following format :

votable

data are written in a XML document following the VOTable standard of the IVOA

html

data are written in a HTML5 document

text

data are written in a plain text document.

How to?

There are two ways to use the scaling service : by writting a client to send a request to the VOS⁴O server and receive and exploit the answer, or through a Web browser or a data transfert software such as curl or wget. In such a case, you should excecute in a terminal :

$> curl "<URL>"

or

$> wget "<URL>"

in which <URL> is described in the HTTP request section.

To write a software requesting the VOS⁴O service, choose a language which implements the communication protocol SOAP. We provided here an example written in PHP:

// Client's ID: provide the name of your project or organisation
                $from = 'MyName';
// Input parameters
$param = array('scale' => 'd(Terre)=1.0',
               'autoscale' => true,
               'scalefactor' => 1.0,
               'unit' => 'm',
               'axis' => 'log',
               'lang' => 'en-us',
               'mime' => 'html',
               'epoch' => 'now');

// Enables or disables the WSDL caching feature
ini_set('soap.wsdl_cache_enabled', 1);
// VOS4O name space
$namespace = 'https://ssp.imcce.fr/webservices/vos4o';
// VOS4O WSDL
$uriwsdl = $namespace.'/vos4o.wsdl';

try {
  // Instantiate 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('scale',array($param));
  // Display the results
  if ($param['mime'] == 'text') {
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: text/plain");
    $res = split(';', $response->result);
    $nbr = count($res);
    $newkey = array_keys($res);
    for ($i=0; $i<$nbr; $i++) { echo $res[$newkey[$i]].PHP_EOL; };
  } else if ($param['mime'] == 'html') {
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: text/html");
    echo $response->result;
  } else {
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: text/xml");
    echo $response->result.PHP_EOL;
  }
} catch (SoapFault $fault) {
  trigger_error("SOAP Fault: {$fault->getTraceAsString()} 
      (faultcode: {$fault->faultcode}, 
       faultstring: {$fault->faultstring})", E_USER_ERROR);
}