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

Miriade Ephemeris Generator

.: ephemcc :.

.: Purpose

This method is intended to people who need to compute the ephemeris of position of Solar system objects.

.: HTTP Request

The Miriade ephemcc service can be accessed using the Miriade query forms. If you are a software/solutions developer, you might want to include the Miriade ephemcc 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/miriade/ephemcc_query.php?[parameters]
where [parameters] is a list of parameters separated by the character &. The allowed parameters are:
ParameterDefinitionLimits or value
-name=<string> The designation (1) of the target Ex.: p:Mars, p:5, a:Pallas, a:1999 TC36(*), c:p/halley
-type=<string> Type of the target (1)
[Optional parameter, default = empty]
Asteroid | Comet | Dwarf Planet | Planet | Satellite
-ep=<string> Requested epoch, expressed in Julian day, ISO format,
or formatted as any English textual datetime
2086308.0 .. 2816788.0
1000-01-01 12h .. 3000-01-01 12h
-nbd=<int> Number of dates of ephemeris to compute
[Optional parameter, default = 1]
1 ≤ nbd ≤ 5000
-step=<string> Step of increment (float) followed by one of
(d)ays or (h)ours or (m)inutes or (s)econds
[Optional parameter, default = 1d]
Ex.: 2.345h or 1d
-tscale=<string> Ephemeris time scale
[Optional parameter, default = UTC]
UTC | TT
-observer=<string> Code or geographic coordinates of the observer's location (2)
[Optional parameter, default = 500]
Ex.: 500 (geocenter), 007 (Paris), @sun, @rosetta, ...
-theory=<string> Planetary theory to use for the calculation
[Optional parameter, default = INPOP]
INPOP | DE405 | DE406
-teph=<int> Type of ephemeris: 1:astrometric J2000, 2:apparent of the date,
3: mean of the date, 4: mean J2000
[Optional parameter, default = 1]
1 | 2 | 3 | 4
-tcoor=<int> Type of coordinates (3): 1:spherical, 2:rectangular, 3: Local coordinates,
4: Hour angle coordinates, 5: dedicated to observation, 6: dedicated to AO observation
[Optional parameter, default = 1]
1 | 2 | 3 | 4 | 5 | 6
-rplane=<int> Reference plane: 1:equator, 2: ecliptic
[Optional parameter, default = 1]
1 | 2
-oscelem=<string> Source of osculating elements for asteroids:
ASTORB or MPCORB
[Optional parameter, default = astorb]
astorb | mpcorb | mpcorb/nea
-mime=<string> Mime type of the results
[Optional parameter, default = votable]
votable | html | text | text/csv | JSON
-output=<string> Comma separated list of options (4)
[Optional parameter, default = blank]
-extrap=<int> Not used (5)
[Optional parameter, default = 0 ]
-from=<string> Word which definite the name of the caller application, or which describes the request any short string (without space)
(*) The space character in the provisional designation of asteroids can be substituted by the underscore ('_') or the HTML character '%20'.
  1. See the HOWTO section for a full description about how to name targets.
  2. The observer location can be defined by its IAU code (e.g. 007), a particular code (e.g. @rosetta), or by its geographic coordinates (longitude, latitude in decimal degrees, and altitude in meters). See the HOWTO section for more information.
  3. See Output parameters section.
  4. The default value 0 means to use the default precision (13 decimals).
  5. See Optional parameters section.

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

.: HTTP Request specific interface

This interface is intended to request specific data used by Miriade.ephemcc method to compute ephemerides:
  • - the list of orbital solutions available for the computation of the ephemerides of the satellites of binary asteroids
  • - the orbital parameters used to compute the ephemerides of a given asteroid or comet
This is done by using the following HTTP request:
http://vo.imcce.fr/webservices/miriade/ephemcc_query.php?-get=<keyword>[&-name=<target>]
where:
ParameterDefinitionLimits or value
-get=<keyword> A keyword from the following list:
genoide_solutions
to get all orbital solutions of satellites of binary asteroids
genoide_best_solutions
to get the best solution for each satellite of binary asteroids
orbital_params
to get orbital parameters of a given asteroid or comet
Keyword
-name=<string> The designation of an asteroid or a comet. When used with keyword:
genoide_solutions, genoide_best_solutions
Leave this parameter empty to get solutions for all binary asteroids,
or provide the name of a binary asteroid to get its satellite orbital solutions.
orbital_params
This parameter is mandatory. Provide the name of the asteroid or comet for
which you request orbital parameters.
Examples:
a:22 or a:Kalliope
c:1P or c:P/Halley
-from=<string> Word which definite the name of the caller application, or which describes the request any short string (without space)

The response to the request is a text/csv document which contains the following information:

genoide_solutions, genoide_best_solutions  More...
 
orbital_params  More...

 

.: Web service

The Miriade Web service provides methods based on SOAP and HTTP POST verb which allow one to interact between its own application and the Miriade service. Here is the useful information to invoke the Miriade ephemcc method:
Web Service URI:
http://vo.imcce.fr/webservices/miriade/miriade.php
Namespace:
http://vo.imcce.fr/webservices/miriade
WSDL:
http://vo.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:
ephemcc  (inputArray)
- The input parameters of the method is an array which must contained the following parameters:
VariableTypeUnitsLimits or valuesDefaultComment
name string designation or URL - none Name or number of the target, or list of targets provided through a file URL (1)
type string - Asteroid | Comet | Dwarf Planet | Planet | Satellite none Type of the target (1)
epoch string epoch
or URL
2086308.0 .. 2816788.0
1000-01-01 12h .. 3000-01-01 12h
none Requested epoch (julian day, ISO format, English textual datetime), or list of epochs provided through an URL (1)
nbd int - 1 ≤ nbd ≤ 5000 1 Number of dates of ephemeris to compute
step string d|h|m|s step ≤ 5000d 1d Step of increment (float) followed by one of (d)ays or (h)ours or (m)inutes or (s)econds
tscale string - UTC | TT UTC Time scale of the ephemeris
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)
theory string - INPOP | DE405 | DE406 INPOP Planetary theory
teph int - 1 | 2 | 3 | 4 1 Type of ephemeris: 1:astrometric J2000, 2:apparent of the date, 3: mean of the date, 4: mean J2000
tcoor int - 1 | 2 | 3 | 4 | 5 | 6 1 Type of coordinates (2): 1:spherical, 2:rectangular, 3: Local coordinates, 4: Hour angle coordinates, 5: dedicated to observation, 6: dedicated to AO observation
rplane int - 1 | 2 1 Reference plane: 1:equator, 2:ecliptic
oscelem string - astorb | mpcorb | mpcorb/nea astorb Source of osculating elements for asteroids: ASTORB or MPCORB
mime string - votable | html | text | text/csv | JSON votable Mime type of the results
output string - - blank Comma separated list of options (3)
extrap int - - 0 Not used
get string - genoide_solutions | genoide_best_solutions | orbital_params blank Use this parameter only to request specific data used by Miriade.ephemcc method to compute ephemerides.
No ephemeris is provided (4)
  1. see the HOWTO or FAQ section of the Miriade documentation for a more complete description.
  2. see Output parameters section.
  3. see Optional parameters section.
  4. see HTTP Request special interface section.

- 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 or flag=-1 mean that an error occured
'status'
the HTTP status-code of the response (e.g. 400: bad request, 404: not found, 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 the JSON data-interchange format (see Howto in SsODNet documentation)
- Examples: click on the following links to get the geocentric astrometric J2000 (spherical) coordinates of Ceres for epoch=2453002.24128009239, observer=500, nbd=5, step=1d, tscale=UTC, theory=INPOP, teph=1, tcoor=1, extrap=0 and:
mime=text, output=--jd
mime=text/csv, output=--iso
mime=json, output=--iso
mime=html, output=--iso,--rv
mime=votable, output=--jd,--rv

.: Output parameters:

The output parameters of the ephemcc method depend on the type of coordinates (arg. -tcoor) and the options (arg. -output) that are choosen by the client. The following tables show the output parameters in function of the value of tcoor argument:
1 - Spherical coordinates   More...
2 - Rectangular coordinates   More...
3 - Local coordinates   More...
4 - Hour angle coordinates   More...
5 - Dedicated to observation   More...
6 - Dedicated to AO observation   More...
Notes:
  1. This column does not exist for the 'text' mime type.
  2. By default the date is expressed in the ISO-8601 format. It can be changed to julian day or calendar date with the -output argument. See Optional parameters section.
  3. A positive value of RV means that the target center is moving away from the observer; while a negative value means that the target center is moving toward the observer.
  4. See the HOWTO section for a full description about how to name targets.
  5. If this value is positive then the satellite is in front of the primary, else it is behind it.

.: Optional parameters:

The optional parameters (-output) can be used to format the display of the date, or to add extra ephemeris data. The available parameters are:
--greg  
to format the epoch as a calendar date.
--iso  
to format the epoch as an ISO-8601 date (default)
--jul  
to format the epoch as a julian day.
--colors(<filter>[,<filter>,...])  
to compute the magnitude of the target for listed filters (only for asteroids).
The recognized filters are: U B V R I Z Y J H Ks u g r i z
Example of request for U, V, B, R, I filters
--thermalFlux(λ,pv,η,ε)  
to compute the thermal flux of the target (only for asteroids) using the Near-Earth Asteroid Thermal Model (NEATM) implemented by the Lagrange laboratory (OCA) and IMCCE.
The computation of the thermal flux depends on the following parameters:
  • - λ: wavelength in micron in the range 4-20 µm (e.g. 10.0) or vector (size≤10) of wavelengths separated by comma and surrounded with square bracket (e.g. [5.0,10.0,20.0])
  • - pv: visible geometric albedo (e.g. 0.26)
  • - η: beaming parameter, equal to one in the case that each point of the surface is in instantaneous thermal equilibrium with solar radiation (e.g. 1.0)
  • - ε: infrared emissivity (e.g. 0.9)
Example of request for λ = [5.0,10.0,20.0]; pv = 0.26; η = 1.0; ε = 0.9
--pafParams(am,h)  
to produce an ephemeris file compatible with the VLT parameter file (PAF) format, to be used for the ESO Phase 2 procedures for Moving Target programmes.
The following cutoff parameters are accepted:
  • - am: airmass limit, lower or equal to 2.6 (default)
  • - h: Sun elevation cutoff, lower or equal to 0° (default)
Example of request for am = 2.2 and h = -10.0°

.: How to consume:

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

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);
// SkyBoT namespace
$namespace = 'http://vo.imcce.fr/webservices/miriade';
// SkyBoT 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_version'=>"SOAP_1_2"));
  // SOAP header
  $header = array('from'=>$from, 'hostip'=>'', 'lang'=>'en');
  $client->__setSoapHeaders(array(new SOAPHeader($namespace, 'clientID', $header)));
  // Call the resolver method
  $response = $client->__soapCall('ephemcc',array($param));
  // Display the results
  if (! empty($param['get']))
  {
    header("HTTP/1.0 ".$response->status);
    if ($response->status < 300) {
      header("Content-Type: text/csv");
    } else {
      header("Content-Type: text/plain");
    }
    echo $response->result."\n";
  
  } 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."\n";
    echo "# Ticket: ".$response->ticket."\n";
    for ($i=0; $i<$nbr; $i++) { echo $res[$newkey[$i]],"\n"; }
  }
  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."\n";
    echo "# Ticket: ".$response->ticket."\n";
    for ($i=0; $i<$nbr; $i++) { echo $res[$newkey[$i]],"\n"; }
  }
  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."\n";
  }
}
catch (SoapFault $fault)
{
    trigger_error("SOAP Fault: {$fault->getTraceAsString()} (faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring})", E_USER_ERROR);
}