Skybot 3D

.: getComet :.

Purpose

This method is intended to people who want to retrieve the state vectors of comets at a reference epoch. The state vectors are those computed and stored in SkyBoT database. No ephemeris computation is performed. The data are just extracted from the database.

HTTP Request

The Skybot3D getComet service can be accessed using the Skybot3D query forms (TBD). If you are a software/solutions developer, you might want to include the Skybot3D getComet service into your application. This can be done by using the web service method or by using the following HTTP request:

http://vo.imcce.fr/webservices/skybot3d/getComet_query.php?[parameters]

Parameter	Definition	Limits
-ep=<string>	Epoch requested, expressed in Julian day or formatted as any English textual datetime (default to now).	2411320.0 .. 2473530.0 1889-11-13 12h .. 2060-03-21 12h
-mime=<string>	Mime type of the results (default to VOTable) (1)	votable \| html \| text \| json
-class=<string>	Allow to retrieve only the comets of the given population classes. Leave empty to get all bodies. Use a comma separated list of classes to get the comets of the given population classes. Use the MySQL wildcard % to match any number of characters, e.g. '%period' requests all Short-period and Long-period comets.	Ex.: %period,%Jupi%,%Halley%]
-limit=<integer>	Maximum number of comets to retrieve (default to all)	Put 0 to retrieve all the known comets
-coord=<string>	Type of coordinates: rectangular for (x,y,z) coordinates, spherical for RA and DEC	rectangular (default) \| spherical
-getFile=<0\|1>	Active only with mime types VOTable and text. If set to 0 then the answer is an object which contains the URL to download the data. If set to 1 then the answer provides directly the data. Be aware that the amount of data to receive can be large (tens of Megabytes).	0 (default) \| 1
-from=<string>	Word which definite the name of the caller application, or which describes the request	any short string (without space)

All input parameters are optional and can be omitted. In that case, the query requests the rectangular ephemerides of all known comets at the current epoch (now). The output is described in the following table and is available in VOTable, HTML, JSon or plain text format (cf. examples).

Web service

The Skybot3D Web service provides methods based on SOAP and HTTP POST verb which allow one to interact between its own application and the Skybot3D service. Here is the useful information to invoke the getComet method:

Web Service URI:: http://vo.imcce.fr/webservices/skybot3d/skybot3d.php
Namespace:: http://vo.imcce.fr/webservices/skybot3d
WSDL:: http://vo.imcce.fr/webservices/skybot3d/skybot3d.php?wsdl
SOAP header:: name of the SOAP header element: 'clientID'; SOAP header's content: array('from' => 'YourName', 'hostip'=>'')
Method:: getComet (inputArray)

The input parameters of the method is an array which must contained the following parameters:

Variable	Type	Units	Limits or values	Default	Comment
epoch	string	-	2411320.0 .. 2473540.0 (1889-11-13 12h .. 2060-03-21 12h)	none	Requested epoch, expressed in Julian day, ISO format or formatted as any English textual datetime
class	string	-	Comma separated list of population classes of comets	empty	Requested population classes of comets as known by SkyBoT.
limit	integer	-	≥ 0	0	Maximum number of comets to retrieve
coord	string	-	rectangular \| spherical	rectangular	Requested type of coordinates of the targets: x,y,z or RA,DEC
mime	string	-	votable \| html \| text \| json	votable	Mime type of the results

The output of the method does not directly provide the ephemerides of comets. Instead it provides an object which contains the information needed to access the data:

'flag': the status of the response: flag=1 means ok; flag=0 means that no body has been found; flag=-1 means that an error occured
'ticket': the Unix timestamp of the answer which can be useful to stamp the request
'nbast': the number of comets contained in the result file
'refdate': the epoch of the ephemeris, in julian day
'filename': the URL of a Bzipped file which contains the result (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 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 in a HTML document using a XSLT processing (Skybot3D XSL style sheet)
text: the data are returned in plain text (CSV-like) with one line of data per comet
json: the data are returned in the JSON (JavaScript Object Notation) data-interchange format

For each comet, the following parameters are given:

coord = rectangular

No.	Definition	Comment
1	Id of the note associated to the comet in COMETPRO database	-
2-4	Heliocentric equatorial mean J2000 position vector (x,y,z)	au
5-7	Heliocentric mean J2000 velocity vector (x',y',z')	au/d
8	Constant term H1 of the total magnitude	mag
9	Coefficient R1 of log(r) of the total magnitude	mag
10	Coefficient D1 of log(delta) of the total magnitude	mag
11	Parameter A1 of non-gravitational force	helio. J2000 eq. frame
12	Parameter A2 of non-gravitational force	helio. J2000 eq. frame
13	Parameter A3 of non-gravitational force	helio. J2000 eq. frame
14	Comet class	-
15	Comet IAU code	-
16	Comet IAU name	-
17	Diameter estimated from the absolute magnitude of the nucleus, assuming albedo=0.04	km
18	Sso type	Only in JSON format

coord = spherical

No.	Definition	Comment
1	Id of the note associated to the comet in COMETPRO database	-
2-3	Heliocentric equatorial mean J2000 right ascension and declination	deg
4	Heliocentric distance	au
5-6	Heliocentric equatorial mean J2000 motion in right ascension and declination	deg/d
8	Constant term H1 of the total magnitude	mag
9	Coefficient R1 of log(r) of the total magnitude	mag
10	Coefficient D1 of log(delta) of the total magnitude	mag
10	Parameter A1 of non-gravitational force	helio. J2000 eq. frame
11	Parameter A2 of non-gravitational force	helio. J2000 eq. frame
12	Parameter A3 of non-gravitational force	helio. J2000 eq. frame
13	Comet class	-
14	Comet IAU code	-
15	Comet IAU name	-
16	Diameter estimated from the absolute magnitude of the nucleus, assuming albedo=0.04	km
17	Sso type	Only in JSON format

Examples: click on the following links to get the state vectors of ten Short-period comets and:

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

How to consume:

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 see how 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,
    'coord' => "rectangular",
    'mime' => "html"
);

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

// Enables or disables the WSDL caching feature
ini_set('soap.wsdl_cache_enabled', 1);
// Skybot3D namespace
$namespace = 'http://vo.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 resolver method
  $response = $client->__soapCall('getComet',array($param));
  // Display the results
  if ($param['mime'] == 'text')
  {
    header("Content-Type: text/plain");
    if ($response->flag > 0) {
      echo "# Flag : ".$response->flag."\n";
      echo "# Ticket : ".$response->ticket."\n";
      echo "# nbCOmets : ".$response->nbsso."\n";
      echo "# refDate : ".$response->refdate."\n";
      echo "# fileName : ".$response->file."\n";
      echo "# fileSize : ".$response->size." bytes\n";
    } else {
      echo "# Flag : ".$response->flag."\n";
      echo "# Ticket : ".$response->ticket."\n";
      echo "# Message : ".$response->result."\n";
  }
  else if ($param['mime'] == 'json')
  {
    header("Content-Type: application/json");
    if ($response->flag > 0) {
      echo $response->result."\n";
    } else {
      echo "# Flag : ".$response->flag."\n";
      echo "# Ticket : ".$response->ticket."\n";
      echo "# Message : ".$response->result."\n";
    }
  }
  else
  {
    header("Content-Type: text/xml;content=x-votable");
    echo $response->result."\n";
  }
}
catch (SoapFault $fault)
{
  trigger_error("SOAP Fault: {$fault->getTraceAsString()} (faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring})", E_USER_ERROR);
}