vOs⁴OVirtual Observatory Solar System Scaling Service for Outreach

API - Web Service

A propos

L'API (interface de programmation applicative) permet d'interroger directement VOS⁴O depuis une application ou un logiciel tiers. Il est ainsi possible de créer une page Web personnelle de mise à l'échelle du système solaire, mais aussi de scripter l'interrogation du service et de récupérer la table et les images générées dans un programme dédié. Deux méthodes sont disponibles pour interroger le service :

• Requête HTTP : interroger simplement le service avec un programme de téléchargement Internet non interactif tels que wget, curl ou un objet XMLHttpRequest du langage Javascript.
• Service Web : interroger le service via son service Web (WS) basé sur les protocoles SOAP+WSDL+HTTP.

L'utilisation de l'API est libre et gratuite pour un usage personnel ou pédagogique et non commercial. Il est fortement recommandé de nous contacter si vous développez une application utilisant le service VOS⁴O afin d'être informé des évolutions.

Veuillez utiliser notre système de rapport d'incident pour signaler un disfonctionnement ou pour faire des demandes d'amélioration du service.

Définition de l'échelle

La définition de l'échelle peut se faire de 3 manières :

x:y

pour spécifier un coefficient multiplicateur X/Y à appliquer à toutes les unités de longueurs. Par exemple, l'échelle 1:1000000 (un millionième) permet de diviser par un million les distances et les diamètres des planètes.

a(planete):x

pour rapporter l'échelle à la valeur x donnée de la distance d'une planète donnée. Par exemple, si le paramètre unite=m (mètre) alors l'échelle a(neptune):7.22 permet de composer un système solaire dans lequel la distance Soleil – Neptune vaut 7.22 mètres.

d(planete):x

pour rapporter l'échelle à la valeur x donnée du diamètre d'une planète donnée. Par exemple, si le paramètre unite=m (mètre) alors l'échelle d(terre):1 permet de composer un système solaire dans lequel le diamètre de la Terre vaut 1 mètre.

Description de la table et des images fournies

La table générée par le service VOS⁴O fournie le diamètre du Soleil, les diamètres des planètes et leurs distances au Soleil mises à l'échelle dans l'unité choisie. Les excentricités des orbites des planètes sont également fournies, ainsi que leurs longitudes moyennes héliocentriques à une époque donnée, exprimées en degrés.

La première image générée par le service VOS⁴O présente graphiquement le système solaire mis à l'échelle en fonction des paramètres choisis. A côté de chaque planète, disposée le long d'un axe gradué en échelle logarithmique respectant leurs distances relatives, figure son diamètre et sa distance au Soleil calculés en fonction de l'échelle et de l'unité choisies.

La deuxième image présente le système solaire vu du dessus. Chaque planète est positionnée sur son orbite en fonction de sa longitude moyenne héliocentrique calculée pour la date donnée. La référence des longitudes est la direction du point vernal moyen (ou équinoxe moyen), matérialisé par le symbole γ.

Requête HTTP

A l'aide d'un programme de téléchargement Internet non interactif (wget, curl), ou à l'aide d'un navigateur Internet, appeler le service à travers son point d'accès HTTP :

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

où [parameters] est une liste de paramètres, définis dans la table 1, séparés par le caractère &. Si tous les paramètres sont omis alors le service renvoie le système solaire mis à l'échelle d'après les valeurs par défaut indiquées dans la table 1.

^* Si le type MIME demandé est VOTABLE alors le paramètre echelleauto vaut 0 quelque soit la valeur fournie.

La réponse d'une requête HTTP est composée d'une table et d'une image, formatée en HTML, VOTable/XML ou en texte simple selon le type MIME choisi (argument -mime).

Exemples de requêtes :

• Le système solaire à l'échelle 1:1000000 (un millionième).
• Le système solaire si la distance Soleil - Neptune est de 7.22 mètres.
• Le système solaire si le diamètre de la Terre vaut 1 mètre.

Web service

Le service VOS⁴O peut être interroger via un Web service basé sur les protocoles SOAP+WSDL+HTTP permettant une interaction directe entre sa propre application et le service.

Web Service URI :

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

Espace de nom :

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

WSDL:

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

Entête SOAP :

nom de l'element de l'entête SOAP : clientID

contenu de l'entête SOAP : array('from' => 'NomProjet', 'hostip'=>'')

Méthode :

scale (inputArray)

Paramètres d'entrée

Les paramètres d'entrée de la méthode scale sont regroupés dans un tableau et doivent définir les variables décrites dans la table 2.

^* Si le type MIME demandé est VOTABLE alors le paramètre autoscale est false quelque soit la valeur fournie.

Paramètres de sortie

La réponse de la méthode 'scale' est un objet contenant les attributs suivants :

'status'

le statut de la réponse, basé sur les codes HTTP : 200 = ok, 400 = mauvaise requête, 404 = non trouvé, 500 = erreur interne.

'ticket'

Horodatage de la réponse.

'result'

Une chaine de caractères contenant la table et les images du système solaire mis à l'échelle.

Type mime

Selon le type MIME sélectionné, la réponse est retournée au format :

votable

les données sont écrites dans un document XML suivant le standard VOTable de l'IVOA

html

les données sont fournies dans un document HTML5

text

les données sont écrites dans un document plein texte.

Comment faire ?

Il y a deux manières d'utiliser le service de mise à l'échelle du système solaire : écrire un client pour envoyer une requête au serveur VOS⁴O puis recevoir et exploiter la réponse, ou utiliser un navigateur Web ou un programme de transfert de données tels que curl ou wget. Dans ce cas, exécuter dans une console la commande :

$> curl "<URL>"

ou

$> wget "<URL>"

où <URL> est décrit dans la section requête HTTP.

Pour écrire un programme client pour invoquer le service VOS⁴O, il faut choisir un langage qui implémente le protocole de communication SOAP. Voici un exemple de client écrit en 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' => 'fr-fr',
               '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]],"\n"; };
  } 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."\n";
  }
} catch (SoapFault $fault) {
  trigger_error("SOAP Fault: {$fault->getTraceAsString()} 
      (faultcode: {$fault->faultcode}, 
       faultstring: {$fault->faultstring})", E_USER_ERROR);
}