Miriade

https://ssp.imcce.fr/webservices/miriade/api/rts.php?[parameters]

The parameters with a default value are optionnal, and they can be omitted (just left blank the value, e.g. ...&-mime=&...). The other input parameters are mandatory. The value of the -extrap parameter defines the number of decimals of the second of time of the rise, transit and setting events, and extrap+1 defines the number of decimal of the local coordinates (azimuth or elevation) of the body at the time of events.

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).

Web Service URI:

https://ssp.imcce.fr/webservices/miriade/miriade.php

Namespace:

https://ssp.imcce.fr/webservices/miriade

WSDL:

https://ssp.imcce.fr/webservices/miriade/miriade.php?wsdl

SOAP header:

name of the SOAP header element: clientID

SOAP header's content: array('from' => 'YourName', 'hostip'=>'', 'lang'=>'en|fr')

Method:

rts (inputArray)

The output of the 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 bodies.

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.

1. Mercury
2. Venus
4. Mars
5. Jupiter
6. Saturn
7. Uranus
8. Neptune
10. Moon
11. Sun

The ephemerides of several bodies can be requested by submitting a list of numbers separated by a comma, e.g. -body=11,10,4,5

By default, when the argument extrap is not defined (or sets to zero), the numerical precision of timings and angles is set to rounded (arc)minute and (arc)second in sexagesimal representation, and to the level of (arc)minute (4 digits) and (arc)second (5 digits) in decimal representation. Defining extrap=x will display all the decimal numbers with x digits, and the (arc)second with x digits in sexagesimal representation. Example: extrap=2 will set the precision to the tenth of a (arc)second for timings and angles in sexagesimal representation (only if time:second and coord:arcsec are used), and will display the timings and angles with 2 digits in decimal representation.

• mime=text
• mime=text/csv
• mime=json
• mime=html
• mime=votable

The output parameters of the rts method are described in the following table.

Notes:

1. The representation and precision of timings depend on the following optional arguments:
   • fmt=timerep:sexagesimal|decimal to display timings in sexagesimal or decimal format,
   • fmt=time:minute|second to display only minute of time, or minute and seconds,
   • extrap to define the number of digits of the seconds of time in sexagesimal format, or to define the number of digits of hours in decimal format.
2. The representation and precision of azimuth and elevation depend on the following optional arguments:
   • fmt=coord:sexagesimal|decimal to display angles in sexagesimal or decimal format,
   • fmt=time:minute|second to display only minute of time, or minute and seconds,
   • extrap+1 to define the number of digits of degrees in decimal format.
3. the timings of the dawn and dusk are provided only for the Sun if argument twilight=1. In this case, depending on the mime type, the twilight timings are empty (text and text/csv) or null (json) for other bodies. If the mime type is votable then a dedicated table with the twilight timings is provided in the main resource of the VOTable.

Remark: the number of digits does not define, in any case, the uncertainty of the computed values. It has to be taken as a computational precision.

{ "id": [ { date_i }, { date_i+1 }, ... ], ... }

{
  "name": string,
  "date": string,
  "dawn-astronomical": [ {} ],
  "dawn-civil": [ {} ],
  "dawn-nautical": [ {} ],
  "rising": [ {} ],
  "transit-sup": [ {} ],
  "setting": [ {} ],
  "dusk-civil": [ {} ],
  "dusk-nautical": [ {} ],
  "dusk-astronomical": [ {} ]
},

"<event_name>": { "hour": string, "coord": string }

"<event_name>": { "hour": float, "coord": float }

"<event_name>": null

$> curl "<URL>"

$> wget "<URL>"

In order to help you to invoke the Miriade 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 rts 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('body' => '11,10,4',
               'epoch' => 2454579.5,
               'nbd' => 1,
               'step' => 1,
               'longitude' => -2.3511111,
               'latitude' => 48.8566667,
               'tz' => 0,
               'mime' => 'text',
               'extrap' => 1,
               'fmt' => "twilight:1,timerep:sexagesimal,time:second,coordrep:decimal,coord:arcmin,az:North"
);

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);
// Miriade namespace
$namespace = 'https://ssp.imcce.fr/webservices/miriade';
// Miriade WSDL
$uriwsdl = $namespace.'/miriade.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('rts',array($param));
   // Display the results
   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");
         header('Content-disposition: attachment;filename="rts.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);
}