Skybot3D

https://ssp.imcce.fr/webservices/skybot3d/api/getAster.php?[parameters]

The output results are described in the following section, and are available in VOTable (default), HTML, plain text format, and JSON object (cf. examples). All input arguments are optional, and their value can be omitted, e.g. ...&-limit=&-mime=&...

Web Service URI:

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

Namespace:

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

WSDL:

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

SOAP header:

name of the SOAP header element: clientID

SOAP header's content: array('from' => 'YourName', 'hostip'=>'')

Methods:

getAster (inputArray)

The output of the methods is an object containing the following attributes:

'flag'

the status of the response: flag=1 means ok; flag=0 or flag=-1 mean that an error occured

'ticket'

the Unix timestamp of the response which can be useful to stamp the request

'status'

the HTTP status-code of the response (e.g. 400: bad request, 422: Unprocessable Entity, 500: internal error)

'nbsso'

the number of objects contained in the result file

'refdate'

the epoch of the ephemeris, in julian day

'file'

the URL of a Bzipped file containing the requested data (extension .bz2)

'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 before 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 from VOTable to HTML by XSLT processing (Skybot3D XSL style sheet)

text

the data are returned in plain text where each value is separated by the pipe '|' character

json

the data are written in a JSON object.

• mime=text
• mime=json
• mime=html
• mime=votable

• If one of the arguments class or limit, or both, are defined and not null, then the output parameters are described in the following tables, depending on the value of the coord argument:
  • Show spherical coordinates

    Field	Definition	Units
    1	Asteroid Id in Skybot database	-
    2-3	Heliocentric mean J2000 equatorial RA and DEC	deg
    4	Heliocentric distance	au
    5-6	Heliocentric mean J2000 equatorial motion ΔRA cos(δ) and Δδ	deg/d
    7	Absolute magnitude (H, G magnitude system)	mag
    8	Slope parameter (H, G magnitude system)	mag/deg
    9	Asteroid class	-
    10	Asteroid name or designation	-
    11	Sso diameter (only in JSON format)	km
    12	Sso type (only in JSON format)	-

  • Show rectangular coordinates

    Field	Definition	Units
    1	Asteroid Id in Skybot database	-
    2-4	Heliocentric mean J2000 equatorial position vector (x, y, z)	au
    5-7	Heliocentric mean J2000 equatorial velocity vector (vx, vy, vz)	au/d
    8	Absolute magnitude (H, G magnitude system)	mag
    9	Slope parameter (H, G magnitude system)	mag/deg
    10	Asteroid class	-
    11	Asteroid name or designation	-
    12	Sso diameter (only in JSON format)	km
    13	Sso type (only in JSON format)	-

• If the both arguments class and limit are not defined or null, which means that all the population of SSOs is requested, then the output is formated according to the native XML format of the mysqldump command. Even if the XML document contains metadata, the following table provides practical informations about the fields:
  • Show XML output

    Field	Definition	Units	Comment
    id_aster	Asteroid Id in Skybot database	-
    ci[1-3]	Heliocentric mean J2000 equatorial position vector (x, y, z)	deg
    ci[4-6]	Heliocentric mean J2000 equatorial velocity vector (vx, vy, vz)	au
    Mv	Visual magnitude	mag	Bowell et al. (1989)
    errpos	Uncertainty on the position	arcsec	Based on ASTORB CEU parameter
    erraju	Internal accuracy of orbit	-	Skybot's internal parameter
    nbboite	Internal cutting	-	Skybot's internal parameter
    ticket	Date of the last update	-	Skybot's internal parameter

  Note: The output parameters and format differ from the previous case for practical reasons. For now, the number of asteroids stored in the tables of the Skybot's database is in the order of one million. Tomorrow it will increase to few millions. Consequently, a classical "SELECT * FROM" query, combined with the formating of the output result, requires a non negligable time of processing. To ensure a short response time, the best thing to do is to dump the whole table. The faster way to do this is to use the mysqldump program which is particularly efficient. In response the data are delivered "as it is", allowing the user to process the data as he wishes. For this task, we offer a simple Python script to convert the XML data in CSV format.

{
  "flag": (int),
  "ticket": (long),
  "status": (int),
  "nbsso": (int),
  "refdate": (float),
  "file": (URL),
  "size(bytes)": (int)
}

And the data are encapsulated in a structure defined as:

{
  "nbsso": (int),
  "refdate": (float),
  "asteroids": [ [ SSO1 ], [ SSO2 ], ... ]
}

$> curl "<URL>"

$> wget "<URL>"

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 write a client with PHP and SOAP which invokes the getAster 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'    => 10,
               'observer' => 500
               'coord'    => 'spherical',
               'mime'     => 'json');
// Boolean to download (1) or not (0) the result file
$getFile = 0;

2/ Define the SOAP options, the namespace and the WSDL URI of SkyBoT web service:

// Enables or disables the WSDL caching feature
ini_set('soap.wsdl_cache_enabled', 1);
// Skybot3D namespace
$namespace = 'https://ssp.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 getAster method
  $response = $client->__soapCall('getAster',$param);
  // Display the results
  if ($param['mime'] == 'text')
  {
    if ($response->flag > 0) {
      if ($getFile == 0) {
        header("HTTP/1.0 ".$response->status);
        header("Content-Type: text/plain");
        echo "# Flag     : ".$response->flag.PHP_EOL;
        echo "# Ticket   : ".$response->ticket.PHP_EOL;
        echo "# nbAster  : ".$response->nbsso.PHP_EOL;
        echo "# refDate  : ".$response->refdate.PHP_EOL;
        echo "# fileName : ".$response->file.PHP_EOL;
        echo "# fileSize : ".$response->size." bytes".PHP_EOL;
      } else {
        $bz = bzopen($response->file,'r');
        $data = '';
        while (!feof($bz)) {
          $buffer = bzread($bz);
          if ($buffer === FALSE) {
            header("HTTP/1.0 500");
            header("Content-Type: text/plain");
            echo 'Error: Skybot3d getAster: Cannot read the bzipped file: '.$js->file;
            exit();
          } else if (bzerrno($bz) !== 0) {
            $error = bzerror($bz);
            header("HTTP/1.0 500");
            header("Content-Type: text/plain");
            echo 'Error: Skybot3d getAster: Cannot read the bzipped file: '.$js->file.', Error: '.$error['errstr'];
            exit();
          } else {
            $data .= $buffer;
          }
        }
        bzclose($bz);
        header("HTTP/1.0 ".$response->status);
        header("Content-Type: text/plain");
        echo $data;
      }
    } else {
      header("HTTP/1.0 ".$response->status);
      header("Content-Type: text/plain");
      echo "# Flag    : ".$response->flag.PHP_EOL;
      echo "# Ticket  : ".$response->ticket.PHP_EOL;
      echo "# Message : ".$response->result.PHP_EOL;
    }
  }
  else if ($param['mime'] == 'json')
  {
    if ($response->flag > 0) {
      if ($getFile == 0) {
        $js = json_decode($response->result);
        header("HTTP/1.0 ".$js->status);
        header("Content-Type: application/json");
        echo $response->result;
      } else {
        $js = json_decode($response->result);
        $status = $js->status;
        $bz = bzopen($js->file,'r');
        $jsdata = '';
        while (!feof($bz)) {
          $buffer = bzread($bz);
          if ($buffer === FALSE) {
            header("Content-Type: text/plain");
            echo 'Error: Skybot3d getAster: Cannot read the bzipped file: '.$js->file;
            exit();
          } else if (bzerrno($bz) !== 0) {
            $error = bzerror($bz);
            header("Content-Type: text/plain");
            echo 'Error: Skybot3d getAster: Cannot read the bzipped file: '.$js->file.', Error: '.$error['errstr'];
            exit();
          } else {
            $jsdata .= $buffer;
          }
        }
        bzclose($bz);
        header("HTTP/1.0 ".$status);
        header("Content-Type: application/json");
        echo $jsdata;
      }
    } else {
      header("HTTP/1.0 ".$js->status);
      header("Content-Type: application/json");
      echo $response->result;
    }
  }
  else
  {
    if ($response->flag > 0) {
      if ($getFile == 0) {
        header("HTTP/1.0 ".$response->status);
        header("Content-Type: text/xml;content=x-votable");
        echo $response->result;
      } else {
        $fdata = Data::getSkybot3DFileFromVOtable($response->result);
        $bz = bzopen(str_replace('${Filename}', $fdata['filename'], $fdata['link']), 'r');
        $votdata = '';
        while (!feof($bz)) {
          $buffer = bzread($bz);
          if ($buffer === FALSE) {
            header("Content-Type: text/plain");
            echo 'Error: Skybot3d getAster: Cannot read the bzipped file: '.$js->file;
            exit();
          } else if (bzerrno($bz) !== 0) {
            $error = bzerror($bz);
            header("Content-Type: text/plain");
            echo 'Error: Skybot3d getAster: Cannot read the bzipped file: '.$js->file.', Error: '.$error['errstr'];
            exit();
          } else {
            $votdata .= $buffer;
          }
        }
        bzclose($bz);
        header("HTTP/1.0 ".$response->status);
        header("Content-Type: text/xml;content=x-votable");
        echo $votdata;
      }
    } else {
      header("HTTP/1.0 ".$response->status);
      header("Content-Type: text/xml;content=x-votable");
      echo $response->result;
    }
  }
} 
catch (SoapFault $fault) 
{
   trigger_error("SOAP Fault: {$fault->getTraceAsString()} (faultcode: {$fault->faultcode},
                               faultstring: {$fault->faultstring})", E_USER_ERROR);
}