M4AST

The method search is intended to people who need to search for asteroid spectra.

If you are a software/solutions developer, you might want to include the M4AST ephemcsearch service into your application. This can be done by using the Web service method or by using the following HTTP request:

https://ssp.imcce.fr/webservices/m4ast/api/search.php?[parameters]

where [parameters] is a list of parameters separated by the ampersand character (&). The allowed parameters are:

Parameter	Definition	Limits or value
`-name=<string>`	The designation of the target	Ex.: a:Pallas, a:1999 TC36, c:p/halley
`-type=<string>`	Type of the target (default: empty)	Asteroid \| Comet \| Dwarf Planet \| Planet \| Satellite
`-observer=<string>`	IAU code of the observer's location (default: 500)	Ex.: 500 (geocenter), 007 (Paris), ...
`-mime=<string>`	Mime type of the results (default: votable)	votable \| html \| text \| text/csv \| json
`-from=<string>`	Word which definite the name of the caller application, or which describes the request	any short string (no space character)

The output results are described in the following section, and are available in VOTable (default), HTML, comma-separated values (CSV), plain text format, and JSON object (cf. examples). Some parameters are optionnal, and their values can be omitted (just left blank the value, e.g. &-mime=&-output=). The input parameters without default value are mandatory.

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

Web Service URI:: https://ssp.imcce.fr/webservices/m4ast/m4ast.php
Namespace:: https://ssp.imcce.fr/webservices/m4ast
WSDL:: https://ssp.imcce.fr/webservices/m4ast/m4ast.php?wsdl
SOAP header:: name of the SOAP header element: clientID; SOAP header's content: array('from' => 'YourName', 'hostip'=>'', 'lang'=>'en|fr')
Method:: search (inputArray)

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

Variable	Type	Units	Limits or values	Default	Comment
`name`	string	designation or URL	-	none	Name or number of the target, or list of targets provided through an URL
`type`	string	-	Asteroid \| Comet \| Dwarf Planet \| Planet \| Satellite	none	Type of the target
`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)
`mime`	string	-	votable \| html \| text \| text/csv \| json	votable	Mime type of the results

The output of the search method 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
'status': the HTTP status-code of the response (e.g. 400: bad request, 422: Unprocessable Entity, 500: internal error)
'ticket': the Unix timestamp of the response which can be useful to stamp the request
'result': a string containing the ephemeris of the requested solar system body with parameters depending on user's options (cf. Output parameters section).

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 (Miriade XSL style sheet)
text: the data are returned in plain text where each block of data is separated by the semi-colon character ';', and fields are separated by one or more blank character. The first block is the keyword '#! ephem' which marks the beginning of the data.
text/csv: the data are returned in plain text where each block of data is separated by the semi-colon character ';', and fields are separated by a comma. The first line provides the ticket (Unix timestamp of the response) and the flag of the response, and the second line provides the field headers.
json: the data are written in a JSON object.

Click on the following links to get:

When the output mime type is the JSON data-interchange format, the ephemerides are encapsulated into a structure defined as follows:

{ "sso": {}, "coosys": {}, "ephemeris": {}, "data": {}, "unit": {} }

where sso provides information about the celestial object:

"sso": { "num": int,
         "name": string,
         "type": string,
         "parameters": {
         "diameter": float,
         "ceu": float,
         "ceurate": float,
         "orbital_period": float,
         "mass": float,
         "dynamical_class": string,
         "taxonomy": { "class": string, "param": string, "source": string } }

where coosys provides information about the celestial reference frame:

"coosys": { "epoch": string, "equinox": string, "system": string }

where ephemeris provides information about the ephemeris computation:

"ephemeris": { "time_scale": string,
               "planetary_theory": string,
               "relativistic_perturbations": string,
               "coordinates": string,
               "reference_frame": { "type": string, "plane": string, "center": string } }

where data contains an array with the ephemerides of the body :

"data": [ { "epoch": float, 
            "ra": float,
            "dec": float,
            "dobs": float,
            "vmag": float,
            "phase": float,
            "solar_elongation": float,
            "mu_ra_cosdec": float,
            "mu_dec": float,
            "dobs_dot": float } ]

and where unit provides the unit of the quantities:

"unit": { "<keyword>": string [, "<keyword>": string, ...] }

where keyword belongs to the list of keywords used inside the document.

You have two ways to use the M4AST web service: by writting a client to send requests to the M4AST 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 M4AST 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 search 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('name' => 'a:ceres',
               'type' => "",
               'epoch' => 2458191.2412800924,
               'nbd' => 5,
               'step' => '1d',
               'tscale' => 'UTC',
               'observer' => '500',
               'theory' => 'INPOP',
               'teph' => 1,
               'tcoor' => 1,
               'rplane' => 1,
               'oscelem' => 'astorb',
               'mime' => 'text',
               'output' => '--jd,--rv'
);

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

// Enables or disables the WSDL caching feature
ini_set('soap.wsdl_cache_enabled', 1);
// M4AST namespace
$namespace = 'https://ssp.imcce.fr/webservices/m4ast';
// M4AST WSDL
$uriwsdl = $namespace.'/m4ast.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'=>'', 'lang'=>'en');
   $client->__setSoapHeaders(array(new SOAPHeader($namespace, 'clientID', $header)));  
   // Call the resolver method
   $response = $client->__soapCall('search',array($param));
   // Display the results
   if (! empty($param['get'])) 
   {
      header("HTTP/1.0 ".$response->status);
      if ($response->status < 300) {
         header("Content-Type: text/csv");
         header('Content-disposition: attachment;filename="orbital_params.csv"'); 
      } else {
         header("Content-Type: text/plain");
      }
      echo $response->result.PHP_EOL;
   }
   else 
   {
      // Affichage du resultat
      if ($param['mime'] == 'text') {
         $res = explode(';', $response->result);
         $nbr = count($res);
         $newkey = array_keys($res);
         header("HTTP/1.0 ".$response->status);
         header("Content-Type: text/plain");
         echo "# Flag: ".$response->flag.PHP_EOL;
         echo "# Ticket: ".$response->ticket.PHP_EOL;
         for ($i=0; $i<$nbr; $i++) { echo $res[$newkey[$i]],PHP_EOL; }
      } else if ($param['mime'] == 'text/csv') {
         $res = explode(';', $response->result);
         $nbr = count($res);
         $newkey = array_keys($res);
         header("HTTP/1.0 ".$response->status);
         if ($response->status < 300) {
            header("Content-Type: text/csv");
         } else {
            header("Content-Type: text/plain");
         }
         echo "# Flag: ".$response->flag.PHP_EOL;
         echo "# Ticket: ".$response->ticket.PHP_EOL;
         for ($i=0; $i<$nbr; $i++) { echo $res[$newkey[$i]],PHP_EOL; }
      } else if ($param['mime'] == 'json') {
         header("HTTP/1.0 ".$response->status);
         header("Content-Type: application/json");
         echo $response->result;
      } 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);
}

search

In search of asteroid spectra

HTTP Request

Web service

Query examples

Structure of the output JSON object

How to consume