vOs⁴OVirtual Observatory Solar System Scaling Service for Outreach

API - Web Service

A propósito

La API (interfaz de programación de aplicaciones) permite interrogar directamente VOS⁴O desde una aplicación o un programa diferente. Uno puede crear su propria página Web de puesta a escala del sistema solar, o interrogar y descargar los resultados del servicio y recuperar la tabla y las imágenes en su propio programa. Hay dos métodos disponibles para interrogar al servicio:

• Búsqueda HTTP : interrogar simplemente al servicio con un programa de descarga Internet no interactivo como wget, curl o un objeto XMLHttpRequest del lenguage Javascript.
• Servicio Web : interrogar al servicio por medio de su servicio Web (WS) basado en los protocolos SOAP+WSDL+HTTP.

La utilización de la API es libre y gratuita para un uso personal o pedagógico y no comercial. Si quieres desarrollar una aplicación que usa VOS⁴O, te recomendamos contactarnos para estar informado de las evoluciones.

Te rogamos que utilices nuestro sistema de informe de incidentes para señalar un problema o para peticiones de mejora del servicio.

Definición de la escala

La definición de la escala puede hacerse de 3 maneras:

x:y

para especificar un coeficiente multiplicador X/Y que se aplique a todas las unidades de longitud. Por ejemplo la escala 1:1000000 (un millonésimo) permite de dividir por un millón las distancias y los diámetros de los planetas.

a(planeta):x

para traer la escala al valor x dado de la distancia de un planeta determinado. Por ejemplo, si el parámetro unidad=m (metro) entonces la escala a(neptune):7.22 permite componer un sistema solar en el cual la distancia Sol – Neptuno vale 7.22 metros.

d(planeta):x

para traer la escala al valor x dado del diámetro de un planeta determinado. Por ejemplo si el parámetro unite=m (metro) entonces la escala d(Tierra):1 permite componer un sistema solar en el cual el diámetro de la Tierra vale 1 metro.

Descripción de la tabla y las imágenes

La tabla generada por el servicio VOS⁴O aporta el diámetro del Sol, los diámetros de los planetas y sus distancias al Sol puestas a escala en la unidad elegida. Las excentricidades de las órbitas de los planetas están también disponibles, al igual que sus longitudes medias heliocéntricas en una época determinada, expresadas en grados.

La primera imagen generada por el servicio VOS⁴O representa gráficamente el sistema solar puesto a la escala en función de los parámetros elegidos. Al lado de cada planeta, dispuesto a lo largo de un eje graduado en escala logarítmica respetando sus distancias relativas, figura su diámetro y su distancia al Sol calculadas en función de la escala y de la unidad elegidas.

La segunda imagen representa el sistema solar visto desde arriba. Cada planeta se posiciona sobre su órbita en función de su longitud media heliocéntrica calculada para la fecha dada. La referencia de las longitudes es la dirección del punto vernal medio (o equinoccio medio), materializado por el símbolo γ.

Búsqueda HTTP

Con la ayuda de un programa de descarga Internet no interactivo (wget, curl), o con la ayuda de un navegador Internet, se puedes llamar al servicio a través de su punto de acceso HTTP :

https://ssp.imcce.fr/webservices/vos4o/scale.php?[parámetros]

en que los [parámetros] es una lista de parámetros definidos dentro de la tabla 1, separados por el caracter &. Si todos los parámetros son omitidos entonces el servicio reenvía el sistema solar puesto a escala a partir de los valores que son indicados por defecto en la tabla 1.

^* Si el tipo MIME requerido es VOTABLE entonces el parámetro autoescala vale 0 sea cual sea el valor aportado.

La respuesta de una búsqueda HTTP está compuesta por una tabla y por dos imágenes, formateada en HTML, VOTable/XML o en texto simple según el tipo MIME elegido (parámetro -mime).

Ejemplos de búsquedas :

• El sistema solar a la escala 1:1000000 (un millonésimo).
• El sistema solar si la distancia Sol - Neptuno es de 7.22 metros.
• El sistema solar si el diámetro de la Tierra vale 1 metro.

servicio Web

El servicio VOS⁴O puede ser interrogado por medio de un servicio Web basado en los protocolos SOAP+WSDL+HTTP permitiendo una interacción directa entre tu propia aplicación y el servicio.

Web Servicio URI :

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

Espacio de nombre :

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

WSDL:

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

Encabezado SOAP :

nombre del elemento del encabezado SOAP : clientID

contenido del encabezado SOAP : array('from' => 'NombreDelProyecto, 'hostip'=>'')

Método :

scale (inputArray)

Parámetros de entrada

Los parámetros de entrada del método scale están agrupados en un cuadro y deben definir las variables descritas en la tabla 2.

^* Si el tipo MIME requerido es VOTABLE entonces el parámetro autoscale es falso en cualquier valor aportado.

Parámetros de salida

La respuesta del método 'scale' es un objeto que contiene los atributos siguientes :

'status'

El estado de la respuesta, basada en los códigos HTTP : 200 = ok, 400 = mala búsqueda, 404 = no encontrado, 500 = error interno.

'ticket'

Marca temporal de la respuesta.

'result'

Una cadena de caracteres que contiene la tabla y las imágenes del sistema solar puesto a escala.

Tipo mime

Según el tipo MIME seleccionado, la respuesta es devuelta al formato :

votable

los datos son escritos en un documento XML siguiendo el estandar VOTable de la IVOA

html

los datos están disponibles en un documento HTML5

text

los datos en un documento de texto.

¿Cómo se hace?

Hay dos maneras de utilizar el servicio de puesta a escala del sistema solar : escribir a un cliente para enviar una búsqueda al servidor VOS⁴O para seguidamente recibir y utilizar la respuesta, o usar un navegador Web o un programa de transferencia de datos como curl o wget. En este caso, ejecutar en una consola la petición :

$> curl "<URL>"

o

$> wget "<URL>"

en que la <URL> está descrita en la sección búsqueda HTTP.

Para escribir un programa cliente que invoque el servicio VOS⁴O, hay que elegir un idioma que implemente el protocolo de comunicación SOAP. He aquí un ejemplo de cliente escrito en PHP:

// Client's ID: provide the name of your project or organisation or yourself
$from = 'MyName';
// Input parameters
$param = array('scale' => 'd(Terre)=1.0',
               'autoscale' => true,
               'scalefactor' => 1.0,
               'unit' => 'm',
               'axis' => 'log',
               'lang' => 'es-es',
               '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);
}