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

Solar System Object Data Mining Tool

.: xmatch :.

.: Purpose

This method is intended to people who need to cross-match sources, extracted from an astronomical archives, with solar system objects and stars.

.: HTTP Request

The AstroId xmatch service can be accessed using the AstroId query forms. If you are a software/solutions developer, you might want to include the AstroId xmatch 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/astroid/xmatch_query.php?[parameters]
where [parameters] is a list of parameters separated by the character &. The allowed parameters are:
ParameterDefinitionLimits or value
-vofile=<string> URL of the VOTable which contains the sources to cross-match Ex.: http://vo.imcce.fr/webservices/astroid/demo/cg0020_6g1119.cat
-identSso=<boolean> Cross-match or not with Sso (1) 0 | 1
-identStars=<boolean> Cross-match or not with stars (1) 0 | 1
-mime=<string> Mime type of the results
[Optional parameter, default = votable]		 votable | html
-epoch=<string> Epoch of the astrometric positions of the sources, expressed in Julian day
or formatted as any English textual datetime (1)
[Optional parameter, default = now] 		Ex.: now, 2012-04-01T17:18:20, 2456019.13792, ...
-observer=<string> Code or geographic coordinates of the observer's location (2)
[Optional parameter, default = 500]		 Ex.: 500 (geocenter), 007 (Paris)
-nccd=<int> Identifier of the group of sources to cross-match (1)
[Optional parameter, default = 1]		 1 ≤ nccd ≤ n
-qualityRef=<int> Quality code (0 .. 100) of the sources to cross-match (1)
[Optional parameter, default = 100]		 0 ≤ qualityRef ≤ 100
-ssoObjectType=<string> Code to indicate which Sso must be crossed with sources
[Optional parameter, default = 110]		 Code composed of 3 integers (0|1) to specify if, respectively, asteroids, planets and comets must be crossed
-ssoPairingRadius=<double> Pairing radius of Sso, in degrees (1)
[Optional parameter, default = 0.0008 deg]		 Maximum distance between a source and a Sso which validates the pairing of the source with the Sso
-ssoDegreeOfFreedom=<int> Degree of freedom of Pierson's test for Sso (1)
[Optional parameter, default = 1]		 1 (cross match based on RA and DEC) or 2 (cross match based on RA, DEC and magnitude)
-ssoPValueThreshold=<int> P-value threshold of Pierson's test for Sso (1)
[Optional parameter, default = 90%]		 0 ≤ P-value ≤ 100
-starCatalog=<string> Catalogue name or number which contains the reference stars (1)
[Optional parameter, default = I/315 (UCAC3)]		 Must be a name or a number recognized by VizieR
-starPairingRadius=<double> Pairing radius of stars, in degrees (1)
[Optional parameter, default = 0.2 deg]		 Maximum distance between a source and a star which validates the pairing of the source with the star
-starDegreeOfFreedom=<int> Degree of freedom of Pierson's test for stars (1)
[Optional parameter, default = 1]		 1 (cross match based on RA and DEC) or 2 (cross match based on RA, DEC and magnitude)
-starPValueThreshold=<int> P-value threshold of Pierson's test for stars (1)
[Optional parameter, default = 95%]		 0 ≤ P-value ≤ 100
-starPosError=<double> Standard astrometric position accuracy of reference stars, in arcsec (1)
[Optional parameter, default = 0.2 arcsec]		 To be used if the star position accuracy is not provided by the catalogue (e.g. ucd='stat.error.sys')
-starMagError=<double> Standard magnitude accuracy of reference stars, in magnitude (1)
[Optional parameter, default = 0.5 mag]		 To be used if the star magnitude accuracy is not provided by the catalogue (e.g. ucd='stat.stdev;em.opt.v')
-from=<string> Word which definite the name of the caller application, or which describes the request Any short string (without space)
  1. see the HOWTO or FAQ section of the AstroId documentation for more information.
  2. The observer location can be defined by its IAU code (e.g. 007), or by its geographic coordinates (longitude, latitude in decimal degrees, and altitude in meters). See the FAQ section for more information.

The output parameters are described in the following table and are available in VOTable (default) or HTML format (cf. examples). Some parameters are optionnal, and their values can be omitted (just left blank the value). The inputs without default value are mandatory.

.: Web service

The AstroId Web service provides methods based on SOAP and HTTP POST verb which allow one to interact between its own application and the AstroId service. Here is the useful information to invoke the AstroId xmatch method:
Web Service URI:
http://vo.imcce.fr/webservices/astroid/astroid.php
Namespace:
http://vo.imcce.fr/webservices/astroid
WSDL:
http://vo.imcce.fr/webservices/astroid/astroid.php?wsdl
SOAP header:
name of the SOAP header element: 'clientID'
SOAP header's content: array('from' => 'YourName', 'hostip'=>'')
Method:
xmatch  (inputArray)
- The input parameters of the method is an array which must contained the following parameters:
VariableTypeUnitsLimits or valuesDefaultComment
vofile string - - none URL of the VOTable which contains the sources to cross-match (1)
identSso boolean - 0 | 1 none Cross-match or not with Sso (1)
identStars boolean - 0 | 1 none Cross-match or not with stars (1)
mime string - votable | html votable Mime type of the results
epoch double julian day 2086308.0 .. 2816788.0
1000-01-01 12h .. 3000-01-01 12h		 none Epoch of the astrometric position of sources
observer string - Code (IAU or special) or geographic coordinates of the observer's location 500 IAU codes of observatories; Geographic coordinates must be expressed in degrees (longitude, latitude) and meters (altitude) (1)
nccd int - 1 ≤ nbd ≤ n 1 Identifier of the group of sources to cross-match (1)
qualityRef int - 0 ≤ qualityRef ≤ 100 100 Quality code (0 .. 100) of the sources to cross-match (1)
ssoObjectType string - 100 | 010 | 001 | 110 | 101 | 011 | 111 110 Code to indicate which Sso must be cross-matched, respectively asteroids, planets and comets
ssoPairingRadius double degrees 0.0008 deg. Pairing radius of Sso, in degrees (1)
ssoDegreeOfFreedom int - 1 | 2 1 Degree of freedom of Pierson's test for Sso (1)
ssoPValueThreshold int - 0 ≤ qualityRef ≤ 100 90 P-value threshold of Pierson's test for Sso (1)
starCatalogue string - VizieR code I/315 Catalogue name or number which contains the reference stars (1)
starPairingRadius double degrees 0.2 deg. Pairing radius of stars, in degrees (1)
starDegreeOfFreedom int - 1 | 2 1 Degree of freedom of Pierson's test for stars (1)
starPValueThreshold int - 0 ≤ qualityRef ≤ 100 95 P-value threshold of Pierson's test for stars (1)
starPosError double arcsec 0.2 arcsec Standard astrometric position accuracy of reference stars, in arcsec (1)
starMagError double mag 0.5 mag Standard magnitude accuracy of reference stars, in magnitude (1)
  1. see the HOWTO or FAQ section of the AstroId documentation for a more complete description.

- The output parameters of the method is an object containing the following attributes:

'flag'
the status of the response: flag=1 means ok, flag=0 means no cross-matched source, and 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 sources and the cross-matched Sso and stars (if any).
- 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 (AstroId XSL style sheet)
- Examples: click on the following links to cross-match these sources (extracted from ??? field of view) with solar system objects and UCAC3 stars, and:
mime=html
mime=votable

.: Output parameters:

The output of the xmatch method is composed of the lists of the cross-matched sources (), and the corresponding Sso and stars, if any.
Notes:
  1. xxx
  2. yyy

.: How to consume:

You have two ways to use the AstroId web service: by writting a client to send requests to the AstroId 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 invoke the AstroId 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 xmatch 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(
     'vofile' => 'http://vo.imcce.fr/webservices/astroid/demo/cg0020_6g1119.cat',
     'identSso' => 0,
     'identStars' => 1,
     'mime' => 'votable',
     'epoch' => 2450276.66970,
     'observer' => 500,
     'nccd' => 2,
     'qualityRef' => 8,
     'ssoObjectType' => '110',
     'ssoPairingRadius' => 0.0008,
     'ssoDegreeOfFreedom' => 1,
     'ssoPValueThreshold' => 90,
     'starCatalogue' => 'I/315',
     'starPairingRadius' => 0.0008,
     'starDegreeOfFreedom' => 1,
     'starPValueThreshold' => 95,
     'starPosError' => 0.2,
     'starMagError' => 0.5
);

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

// Enables or disables the WSDL caching feature
ini_set('soap.wsdl_cache_enabled', 1);
ini_set('default_socket_timeout', 3600);
// SOAP version
$soapVersion = 'SOAP_1_2';
// SkyBoT namespace
$namespace = 'http://vo.imcce.fr/webservices/astroid';
// SkyBoT WSDL
$uriwsdl = $namespace.'/astroid.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('xmatch',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 = split(';', $response->result);
    $nbr = count($res);
    $key = array_keys($res);
    for ($i=0; $i<$nbr; $i++) { echo $res[$key[$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);
}