vOs⁴OVirtual Observatory Solar System Scaling Service for Outreach

API - Web Service

Acerca da API

A API (Interface de Programação de Aplicações - "Application Programming Interface") permite pesquisar diretamente no VOS⁴O a partir de uma aplicação ou software de terceiros. É por isso possível criar uma página Web pessoal para fazer a escala do Sistema Solar, e também de escrever um código que use o serviço e recupere a tabela e as imagens geradas por um programa a isso dedicado. Dois métodos estão disponíveis para usar este serviço:

• Pedido HTTP: simplesmente usar o serviço para pesquisar com um programa não-interativo de downloads da Internet como wget, curl ou um objeto XMLHttpRequest em linguagem de Javascript.
• Serviço Web: usar o serviço através do seu Serviço Web (WS), baseado nos protocolos SOAP+WSDL+HTTP.

Usar a API é gratuito e livre para fins pessoais ou pedagógicos não comerciais. É altamente recomendado contactar-nos se criar uma aplicação que utilize o serviço VOS⁴O para receber informações e atualizações.

Por favor utilize o nosso sistema de relatório de erros para avisar de qualquer erro ou pedir novas funcionalidades.

Definição da Escala

Há três maneiras diferentes de definir a escala:

x:y

para especificar um coeficiente multiplicativo X/Y a aplicar a todas as unidades de comprimento. Por exemplo, a escala 1:1000000 (um milionésimo) permite dividir por um milhão as distâncias e os diâmetros dos planetas.

a(planeta):x

para fixar uma escala ao valor x definido pela distância a um dado planeta. Por exemplo, se o parâmetro tiver unidade=m (metro), então a escala a(neptuno):7.22 permite criar um Sistema Solar no qual a distância Sol – Neptuno seja 7,22 metros.

d(planeta):x

para fixar uma escala ao valor x definido pelo diâmetro de um dado planeta. Por exemplo, se o parâmetro tiver unidade=m (metro), então a escala d(terra):1 permite criar um Sistema Solar no qual o diâmetro da Terra seja 1 metro.

Descrição da tabela e das imagens fornecidas

A tabela gerada pelo serviço VOS⁴O fornece o diâmetro do Sol, os diâmetros dos planetas e as suas distâncias ao Sol colocadas à escala na unidade escolhida. As excentricidades das órbitas dos planetas também são fornecidas, bem como as suas longitudes heliocêntricas médias num dado momento, expressas em graus.

A primeira imagem gerada pelo serviço VOS⁴O apresenta graficamente o Sistema Solar à escala, em função dos parâmetros escolhidos. Junto a cada planeta, desenhado ao longo de um eixo numa escala logarítmica relativa às suas distâncias, estão o seu diâmetro e distância ao Sol calculados em função da escala e unidade escolhidas.

A segunda imagem gerada apresenta o Sistema Solar visto de cima. Cada planeta está colocado na sua órbita em função da sua longitude heliocêntrica média calculada para a data escolhida. A referência para as longitudes é a direção do ponto vernal médio (ou equinócio médio), representado pelo símbolo γ.

Pedido HTTP

Com a ajuda de um programa não interativo de download da Internet (como wget, curl), ou com a ajuda de um navegador da Internet, pode usar o serviço através do seu ponto de acesso HTTP:

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

onde [parameters] é uma lista de parâmetros, definidos na Tabela 1, separados pelo caracter &. Se algum parâmetro não for definido, o serviço forma o Sistema Solar à escala dos valores indicados na Tabela 1.

^* Se o formato MIME for VOTABLE, o parâmetro autoescala será 0 independentemente do valor escolhido.

O resultado da pesquisa HTTP consiste numa tabela e duas imagens, formatadas em HTML, VOTable/XML ou texto simples, segundo o parâmetro MIME escolhido (parâmetro -mime).

Exemplos de pesquisas:

• O Sistema Solar à escala 1:1000000 (um milionésimo).
• O Sistema Solar com uma distância Sol - Neptuno de 7,22 metros.
• O Sistema Solar com um diâmetro da Terra de 1 metro.

Serviço Web

O serviço VOS⁴O pode ser usado via um Serviço de Web baseado nos protocolos SOAP+WSDL+HTTP que permitem uma interação direta entre a sua própria aplicação e o serviço.

Serviço Web URI:

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

Namespace:

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

WSDL:

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

Cabeçalho SOAP:

Nome do cabeçalho SOAP: clientID

Conteúdo do cabeçalho SOAP: array('from' => 'NomProjet', 'hostip'=>'')

Método:

escala (inputArray)

Parâmetros de input

Os parâmetros de input dos métodos de escala são agrupados numa tabela e devem definir as variáveis descritas na Tabela 2.

^* Se o tipo MIME pedido for VOTABLE, o parâmetro autoescala é falso independentemente do valor fornecido.

Parâmetros de output

O resultado do método 'escala' é um objeto com os seguintes atributos:

'estatuto'

O estatuto da resposta, baseado no código HTTP: 200 = ok, 400 = mau pedido, 404 = não encontrado, 500 = erro interno.

'bilhete'

Data da resposta.

'resultado'

Uma string que contém a tabela e as imagens do Sistema Solar feitas à escala.

Tipo MIME

Segundo o tipo MIME selecionado, a resposta é fornecida no seguinte formato:

votable

dados escritos num documento XML que segue o padrão VOTable da IVOA.

html

dados escritos num documento HTML5.

texto

dados escritos num documento de texto simples.

Como usar?

Há duas maneiras de usar o serviço de escala do Sistema Solar: escrever um cliente para enviar um pedido ao servidor VOS⁴O e receber e explorar a resposta, ou utilizar um navegador Web ou um programa de transferência de dados como curl ou wget. Nesse caso, pode executar num terminal o seguinte comando:

#> curl "<URL>"
ou
#> wget "<URL>"

onde <URL> é descrito na secção Pedido HTTP.

Para escrever um programa cliente que use o serviço VOS⁴O, é necessário escolher uma língua que implemente o protocolo de comunicação SOAP. Apresentamos aqui um exemplo escrito em PHP:

// ID do Cliente: fornece o nome do seu projeto ou organização
$from = 'MyName';
// Parâmetros de input
$param = array('escala' => 'd(Terra)=1.0',
               'autoescala' => true,
               'fatordeescala' => 1.0,
               'unidade' => 'm',
               'eixo' => 'log',
               'língua' => 'pt-pt',
               'mime' => 'html',
               'data' => 'now');

// Permite ou impede o recurso ao armazenamento em cache WSDL
ini_set('soap.wsdl_cache_enabled', 1);
// Espaço de nome VOS4O
$namespace = 'http://ssp.imcce.fr/webservices/vos4o';
// VOS4O WSDL
$uriwsdl = $namespace.'/vos4o.wsdl';

try {
  // Instanciar o cliente
  $client = new SoapClient($uriwsdl, array('exceptions'=>1));
  // SOAP header
  $header = array('from'=>$from, 'hostip'=>'');
  $client->__setSoapHeaders(array(
     new SOAPHeader($namespace, 'clientID', $header)
  ));  
  // Chamar o método de resolução
  $response = $client->__soapCall('scale',array($param));
  // Apresentar os resultados
  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);
}