Skybot3D

https://ssp.imcce.fr/webservices/skybot3d/api/getComet.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:

getComet (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	Comet 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-9	Parameters for the calculation of the total magnitude: H1 the constant term of magnitude, R1 the coefficient of log(r) and D1 the coefficient of log(Delta). The total magnitude is calculated by m = H1 + R1.log(r) + D1.log(Delta) where r is the distance of the comet to the Sun in au and Delta the distance of the comet to the observer in au	mag
    10-12	Parameters to compute the non-gravitational forces in the heliocentric J2000 equatorial frame.
    13	Comet class	-
    14	IAU code of the comet (uniq identifier)	-
    15	IAU name of the comet (common name)	-
    16	Estimation of the diameter based on the constant term of the nuclear magnitude and an albedo of 0.04 (only in the JSON output)	km
    17	Comet type (only in the JSON output)	-

  • Show rectangular coordinates

    Field	Definition	Units
    1	Comet 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-10	Parameters for the calculation of the total magnitude: H1 the constant term of magnitude, R1 the coefficient of log(r) and D1 the coefficient of log(Delta). The total magnitude is calculated by m = H1 + R1.log(r) + D1.log(Delta) where r is the distance of the comet to the Sun in au and Delta the distance of the comet to the observer in au	mag
    11-13	Parameters to compute the non-gravitational forces in the heliocentric J2000 equatorial frame.
    14	Comet class	-
    15	IAU code of the comet (uniq identifier)	-
    16	IAU name of the comet (common name)	-
    17	Estimation of the diameter based on the constant term of the nuclear magnitude and an albedo of 0.04 (only in the JSON output)	km
    18	Comet type (only in the JSON output)	-

• 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	Comet 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
    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: Although today we know a few thousand comets, the output parameters and format differ from the previous case in order to be in agreement with the output results of the getAster method.

{
  "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),
  "comets": [ [ 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 getComet 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 getComet method
  $response = $client->__soapCall('getComet',$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 getComet: 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 getComet: 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 getComet: Cannot read the bzipped file: '.$js->file;
            exit();
          } else if (bzerrno($bz) !== 0) {
            $error = bzerror($bz);
            header("Content-Type: text/plain");
            echo 'Error: Skybot3d getComet: 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 getComet: Cannot read the bzipped file: '.$js->file;
            exit();
          } else if (bzerrno($bz) !== 0) {
            $error = bzerror($bz);
            header("Content-Type: text/plain");
            echo 'Error: Skybot3d getComet: 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);
}