Logo IMCCE-VOParis

THE IMCCE VIRTUAL OBSERVATORY
SOLAR SYSTEM PORTAL
Observatoire de Paris / CNRS

Logo IMCCE
Portal Home Page | Report issue | Legal notice | Contact us

The Virtual Observatory Sky Body Tracker

.: skybotconesearch :.

.: Purpose

This method is intended to people who need to know which solar system objects (asteroids, planets, natural satellites and comets) are located into a field of view of given celestial coordinates and radius at a given epoch.

.: HTTP Request

The Skybot Cone-Search service can be accessed using the SkyBoT query forms. If you are a software/solutions developer, you might want to include the Skybot Cone-Search 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/skybot/skybotconesearch_query.php?[parameters]
where [parameters] is a list of parameters separated by the character &, which may be composed in two ways:
- standard Simple Cone Search (SCS) interface
the parameters are encoded in the URL with standard keywords providing a right ascension, a declination and a search radius, all in degrees (J2000), of the queried field of view in the sky. A non standard but mandatory keyword (EPOCH) must be added to specify the epoch at which you are searching for solar system objects. The parameters are described in Table 1.
- non standard interface
the parameters are encoded in the URL with dedicated keywords providing the relevant information to search the solar system objects located in a given field of view. The parameters are described in Table 2.
If you choose to query SkyBoT using the SCS standard interface, you may also use the non standard keywords by adding them before the standard ones.
Table 1: Standard Simple Cone Search interface
ParameterDefinitionUnitLimits
EPOCH=<string> Requested epoch, expressed
in Julian day or ISO dateTime (1)
- 2411320.0 .. 2469880.0
1889-11-13 12h .. 2050-03-14 12h
RA=<double> Right ascension of the FOV center degree 0° .. 360° (decimal)
DEC=<double> Declination of the FOV center degree -90° .. +90° (decimal)
SR=<double> Radius of the FOV degree 0 .. 20° (decimal)
VERB=<int> Level of output parameters - 1, 2, 3 which correspond, respectively,
to object, basic, all
TOP=<int> Similar to SIA/TOP or TAP/MAXREC parameters (2) - optional parameter
Default is empty
  1. the EPOCH parameter is not a standard keyword of the Simple Cone Search protocol, but it is mandatory to search solar system objects in a field of view. This keyword (which could be named differently) will be added to the next release of the SCS protocol.
  2. If TOP>0 then a query to Skybot status is performed to check if the service is alive before sending the query to the conesearch method. If TOP=1 then the conesearch query is not performed and the client receives a VOTable with the status response. If TOP>1 then the conesearch query is send if no status error occurs, and the client does not receive a status message.
Table 2: Non standard iterface
ParameterDefinitionUnitLimits
-ep=<string> Epoch requested, expressed in Julian day
or formatted as any English textual datetime
- 2411320.0 .. 2469880.0
1889-11-13 12h .. 2050-03-14 12h
-ra=<double> Right ascension or ecliptic longitude of the FOV center (4) degree 0° .. 360° (decimal)
-dec=<double> Declination or ecliptic latitude of the FOV center (4) degree -90° .. +90° (decimal)
-rs=<double>
-rm=<double>
-rd=<double>

 

-bs=<string>
-bm=<string>
-bd=<string>
Radius of the FOV
OR (1)
size of the FOV as ΔαxΔδ
arcsec
arcmin
degree

 

arcsec
arcmin
degree
0 .. 36000 arcsec
0 .. 600 arcmin
0 .. 10 degrees

 

0 .. 72000 arcsec
0 .. 1200 arcmin
0 .. 20 degrees
-mime=<string> Mime type of the results - votable | html | text
-output=<string>
or
-out=<string>
Output parameters
(-out is deprecated)
- object | basic | obs | all
-loc=<string> Code of the observer location (2) - Optional parameter
list of IAU codes
Default: 500 (geocenter)
-filter=<double> Filter to retrieve only objects with a position error lesser than the given value arcsec optional parameter
0 implies no filter
Default: 120 arcsec
-objFilter=<string> Code to indicate which objects must be sought in the FOV - optional parameter
Code composed of 3 integers (0|1) to specify if, respectively, asteroids, planets and comets must be sought
Default: 111 (all objects)
-refsys=<string> Code to indicate the reference plane of coordinates - optional parameter
EQJ2000 (default) | ECJ2000
-from=<string> Word which definite the name of the caller application, or which describes the request - any short string (without space)
-top=<int> Similar to SIA/TOP or TAP/MAXREC parameters (3) - optional parameter
Default is empty
  1. One should use the radius of a circle or the sizes of a box to define the field of view. In the case of a box, the second value of the size can be omitted (e.g -bm=15 and not -bm=15x15) to define a square box (i.e same size in RA and DEC). If both the radius and the size of the FOV are omitted then a radius of 15 arcmin is used by default.
  2. The observer location can be defined by its IAU observatory code or by a particular code (cf. FAQ section).
  3. If -top>0 then a query to Skybot status is performed to check if the service is alive before sending the query to the conesearch method. If -top=1 then the conesearch query is not performed and the client receives a VOTable with the status response. If -top>1 then the conesearch query is send if no status error occurs, and the client does not receive a status message.
  4. If -refsys=ECJ2000 then this fields are read as the ecliptic longitude and latitude.

The output is described in the following table and is available in VOTable, HTML or plain text format (cf. examples). The -mime and -output parameters are optionnal and their values can be omitted (just write nothing or &-mime=&-output= without values). In this case, the output is the basic one in VOTable format. The other inputs are mandatory.

.: Web service

The SkyBoT Web service provides methods based on SOAP and HTTP POST verb which allow one to interact between its own application and the SkyBoT services. Here is the useful information to invoke the skybotResolver method:
Web Service URI:
http://vo.imcce.fr/webservices/skybot/skybot.php
Namespace:
http://vo.imcce.fr/webservices/skybot
WSDL:
http://vo.imcce.fr/webservices/skybot/skybot.php?wsdl
SOAP header:
Name of the SOAP header element: 'clientID'
SOAP header's content (*): array('from' => 'YourName', 'hostip'=>'')
Method:
skybotconesearch  (inputArray)

(*) Note that you should preferably leave the header field 'hostip' empty.

- The input parameters of the method is an array which must contained the following parameters:
VariableTypeUnitsLimits or valuesDefaultComment
epoch string - 2411320.0 .. 2469880.0
(1889-11-13 12h .. 2050-03-14 12h)
none Requested epoch, expressed in Julian day, ISO format
or formatted as any English textual datetime
alpha double degree 0° .. 360° (decimal) none Right ascension or ecliptic longitude of the FOV center
delta double degree -90° .. +90° (decimal) none Declination or ecliptic latitude of the FOV center
radius string arcsec 0 .. 108000 arcsec
or
0 .. 216000 arcsec
none Radius (single value)
or
sizes (<value>x<value>) of the FOV
mime string - votable | html | text votable Mime type of the results
output string - object | basic | obs | all basic Output parameters
observer string - Code of observer location 500 IAU observatory code or particular code
filter double arcsec 0 implies no filter 120 Filter on the error of position: only targets with position error lesser that the given value are retrieved
objFilter string - 100 | 010 | 001 | 110 | 101 | 011 | 111 111 Code to indicate which objects must be sought in the FOV, respectively asteroids, planets and comets
refsys string - EQJ2000 | ECJ2000 EQJ2000 Code to indicate the reference plane of coordinates
- The output of the method is an object containing the following attributes:
'flag'
the status of the response: flag=1 means that a body has been found; 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
'result'
a string containing the list of the solar system bodies in the FOV with the following parameters:
No.DefinitionUnitsobjectbasicobsall
1 object number (blank if unnumbered) - x x x x
2 object name (official or preliminary designation) - x x x x
3,4 astrometric J2000 geocentric equatorial or ecliptic coordinates
at the given epoch
α in hms, δ in dms
lon in deg, lat in deg
x x x x
5 class - x x x x
6 visual magnitude - x x x x
7 error on the position arcsec x x x x
8 body-to-center angular distance arcsec x x x x
9,10 motion on the celestial sphere (Δα'cos(δ), Δδ) or (Δlon cos(lat), Δlat) arcsec/h   x x x
11 geocentric distance AU   x x x
12 heliocentric distance AU   x x x
13 Phase angle degree     x x
14 Solar elongation degree     x x
15..20 mean J2000 heliocentric equatorial or ecliptic vector position and
motion at epoch T0
AU and AU/d       x
21 T0, epoch of the position vector Julien Day       x
- 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 (SkyBoT XSL style sheet)
text
the data are returned in plain text where each block of data is separated by the semi-colon character ';' and each value in a block is separated by the pipe '|' character
- Examples: click on the following links to get the result for epoch=now, alpha=148.666, delta=16.3833, radius=1200, observer=500, filter=120, refsys=EQJ2000, objFilter=110 and:
mime=text, output=object
mime=html, output=basic
mime=votable, output=all

.: How to consume:

You have two ways to use the SkyBoT web service: by writting a client to send requests to the SkyBoT server and to receive and analyze the response, or by using a command line interface and a data transfert program such as curl or wget. For that, just execute one of the following commands in a console:
#> curl "<URL>"
or
#> wget "<URL>"
where <URL> is described in section HTTP request.

In order to help you to write a client to invoke the SkyBoT web service, we provide some clients written in differents languages. Here are some detailed explanations to how to write a client with PHP and SOAP which invokes the skybotconesearch 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' => 2453384.92153935181,
    'alpha' => 148.67,
    'delta' => 16.3838,
    'radius' => '900',
    'mime' => "html",
    'output' => "basic",
    'observer' => "500",
    'filter' => "120",
    'objFilter' => "111",
    'refsys' => "EQJ2000"

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);
// SOAP version
$soapVersion = 'SOAP_1_2';
// SkyBoT namespace
$namespace = 'http://vo.imcce.fr/webservices/skybot';
// SkyBoT WSDL
$uriwsdl = $namespace.'/skybot.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_version'=>$soapVersion));
  // SOAP header
  $header = array('from'=>$from, 'hostip'=>'');
  $client->__setSoapHeaders(array(new SOAPHeader($namespace, 'clientID', $header)));
  // Call the resolver method
  $response = $client->__soapCall('skybotconesearch',array($param));
  // Display the results
  if ($param['mime'] == 'text')
  {
    header("Content-Type: text/plain");
    echo "Flag: ".$response->flag."\n";
    echo "Ticket: ".$response->ticket."\n";
    echo "Result: ";
    $res = explode(';', $response->result);
    $nbr = count($res);
    $newkey = array_keys($res);
    for ($i=0; $i<$nbr; $i++) { echo $res[$newkey[$i]],"\n"; };
  }
  else
  {
    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);
}