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

.: ephemph :.

.: Purpose

This method is intended to people who need to compute the apparent aspect - or physical ephemeris - of Solar system objects.

.: HTTP Request

The Miriade ephemph service can be accessed using the Miriade query forms. If you are a software/solutions developer, you might want to include the Miriade ephemph 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/ephemph_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(*) of the target Ex.: p:Mars, p:5, a:Pallas, a:1999_TC36, c:p/halley
-type=<string> Optional parameter to define the type of the target Asteroid | Comet | Dwarf Planet | Planet | Satellite
-ep=<string> Requested epoch, expressed in Julian day
or formatted as any English textual datetime
2086308.0 .. 2816788.0
1000-01-01 12h .. 3000-01-01 12h
-nbd=<int> Number of date of ephemerides 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
-so=<int> Spin axis solution number (2)
[Optional parameter, default = 1]
1 ≤ so ≤ 99
-observer=<string> Code of the observer location (3)
[Optional parameter, default = 500]
Ex.: 500 (geocenter), 007 (Paris)
-mime=<string> Mime type of the results votable | html | text | image
-view=<string> Output format of the generated image
[Optional parameter, default = none]
wired[:eps|png] | fits | png | eps | none
-rv=<int> Compute radial velocity or not
[Optional parameter, default = 0]
0 | 1
-anim=<int> Mode animate: draw an image for each date, else draw an image only for the first date
[Optional parameter, default = 0]
0 | 1
-print=<int> Display ephemeris date results or not
[Optional parameter, default = 0]
0 | 1
-visu=<string> Comma separated list of options to pass to the image generator
[Optional parameter, default = blank]
Inactive
-output=<string> Comma separated list of options to format the output of the ephemeris (5)
[Optional parameter, default = blank]
-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 or FAQ section of the Miriade documentation for a full description about how to name targets.
  2. The spin solution number can be obtained through the dedicated GET API of Miriade.ephemph.
  3. The observer location can be defined by its IAU code or a particular code (cf. FAQ section).
  4. see Output parameters section.
  5. see Optional parameters section.

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

.: HTTP Request specific interface

This interface must only be used to request the list of spin elements available for the computation of the physical ephemerides of asteroids in Miriade.ephemph. This is done by using the following HTTP request:
http://vo.imcce.fr/webservices/miriade/ephemph_query.php?-get=<string>[&-name=<target>]
where:
ParameterDefinitionLimits or value
-get=<keyword> keyword = spin spin
-name=<string> The designation of the asteroid: <prefix>:<name>
Leave the name part empty to get the spins of all asteroids,
or provide the name of an asteroid to get its spin solutions.
Ex.: a:pallas, a:Kalliope
-mime=<string> Mime type of the results, optional, default text/csv text/csv | text
-from=<string> Word which definite the name of the caller application, or which describes the request any short string (without space)
- Examples: click on the following links to get:

- The request returns a CSV or a plain text document which contains the following information:

ParameterDefinitionUnit
Id Official number of the primary (blank if unknown)
Name Name or designation of the asteroid
SystRef Reference system, e.g. EQJ2000 for equator J2000, or ECJ2000 for ecliptic J2000
So Spin ID
lambda (deg) Longitude of the spin axisdeg
beta (deg) Latitude of the spin axisdeg
W0 (deg) Zero phase angle of rotationdeg
Sid. Period (d) Sidereal period of rotationdays
Zero phase Epoch (JD)Zero phase epoch of rotationjulian day
TS Reference time scale of the zero phase epoch
a/b Ratio of semi-principal axes a and b (tri-axial ellipsoid)
b/c Ratio of semi-principal axes b and c (tri-axial ellipsoid)
R_a (km) Radius of the a axiskm
R_b (km) Radius of the b axiskm
R_c (km) Radius of the c axiskm
To query the physical ephemerides of an asteroid with a specific spin solution, use the given spin ID as the value of the -so argument.

.: 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 ephemph 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:
ephemph  (inputArray)
- The input parameters of the method is an array which must contained the following parameters:
VariableTypeUnitsLimits or valuesDefaultComment
name string - - none Name or number of the target (1)
type string - Asteroid | Comet | Dwarf Planet | Planet | Satellite none Type of the target
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 date of ephemerides 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
so int - 1 ≤ so ≤ 99 1 Spin axis solution number (2)
observer string - IAU observatory or particular code (3) 500 IAU code of the observer location
mime string - votable | html | text | image votable Mime type of the results
view string - wired[:eps|png] | fits | png | eps | none none Output format of the generated image
rv int - 0 | 1 0 Compute radial velocity or not
anim int - 0 | 1 0 Mode animate: draw an image for each date, else draw an image only for the first date
print int - 0 | 1 0 Display ephemeris results or not
visu string - Inactive blank Comma separated list of options to pass to the image generator
output string - - blank Comma separated list of options (4)
  1. see the HOWTO or FAQ section of the Miriade documentation for a full description about how to name targets.
  2. The spin solution number can be obtained through the dedicated GET API of Miriade.ephemph.
  3. The observer location can be defined by its IAU code or a particular code (cf. FAQ section).
  4. see Optional parameters 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
'ticket'
the Unix timestamp of the answer which can be useful to stamp the request
'result'
a string containing the ephemeris of the requested solar system body (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 in a HTML document using a 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 ;. The block of data starts with the keyword #! ephem (if print=1 then it is the first block). The lines which contain the URL to download the generated images start with the keyword #! image <idx> where <idx> starts at 0 and ends at nbd-1.
image
- Examples: click on the following links to get the geocentric physical ephemeris of asteroid Kleopatra for epoch=2453002.24128009239, nbd=5, step=1d, so=1, observer=500, rv=0, print=1, output=--iso, and:
mime=text, view=none, anim=0 (data only)
mime=html, view=wired:png, anim=1 (data & images)
mime=votable, view=wired:png, anim=1 (data & images)
mime=image, view=wired:png, anim=0 (image only)

.: Optional parameters:

The optional parameters (-output) can be used to format the display of the date:
--greg  
format the epoch as a calendar date.
--iso  
format the epoch as an ISO-8601 date (default)
--julian  
format the epoch as a julian day.
or to add extra ephemeris data:
--coord:eq  
add the spherical equatorial coordinates of the target (RA, DEC), apparent frame (true equator, equinox of the date)
--coord:eq2000  
add the spherical equatorial coordinates of the target (RA, DEC), mean J2000 frame (mean equator, mean equinox)
--coord:ec  
add the spherical ecliptic coordinates of the target (λ, β), apparent frame (true equator, equinox of the date)
--coord:rect  
add the rectangular equatorial coordinates of the target (x,y,z), apparent frame (true equator, equinox of the date)

.: Output parameters:

The following table shows the output parameters of the ephemph method.
Col. Definition Units Format Label
1 Gregorian Date datetime default to ISO-8601 Date UTC
2,3 Sub-Earth point longitude and latitude (1) degree decimal SEP
4,5 Sub-Solar point longitude and latitude (2) degree decimal SSP
6 North pole position angle w.r.t. celestial north pole degree decimal PA_n
7 Angular distance between the pole and the center of the body arcsec decimal d_p
8 Visual magnitude - decimal Mv
9 Phase angle degree decimal i
10 Body angular radius arcsec decimal R_app
11 Range to observer AU decimal Dg
12 Heliocentric distance AU decimal Dh
13 Angle of position of the equator of intensity degree decimal PA
14 Length of the right-side segment on the equator of intensity which is not illuminated (on the surface of the apparent disc of planet) arcsec decimal Q
15,16
[,17]
Coordinates of the target expressed in spherical or rectangular format in the chosen reference frame (true or mean) hms | dms
au
sexagesimal
decimal
RA,DEC | Lambda,Beta
x,y,z
  1. In the case of the Moon, the selenocentric coordinates of the Earth take account of the lunar surface periodic oscillations or (optics and physics) librations, which allow to discover up to 59% of its surface seen from the Earth.
  2. In the case of the Moon, we provide the colongitude of the Sun, defined as the East selenocentric longitude of the terminator. Colongitudes 270°, 180°, 90° and 0° correspond, at a few nearest hours, to new moon, first quarter, full moon and last quarter.

.: Graphical output:

When the argument view is not none, the physical ephemerides are completed by figures, which show graphically the apparent aspect of the target at each epoch. Two graphic modes are available:
- wired style
view=wired[:eps|png] : the target is modeled with an ellipsoid of revolution (grid 5°x5°) projected on the sky plane.
The red and yellow marks show respectively the sub-earth and sub-solar points, the cyan great circle materializes the prime meridian, and the grey zone enlights the solar phase.
- 3D shape model
view=fits|png|eps : the target is modeled with a 3D shape model, finely rendered with our Planetary Scene Viewer software.
This mode is not functional for now. Next release scheduled in July 2017.

.: 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 ephemph 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:kleopatra',
    'type' => '',
    'epoch' => 2453002.24128009239,
    'nbd' => 5,
    'step' => '1h',
    'tscale' => 'UTC',
    'so' => 1,
    'observer' => '500',
    'mime' => 'text',
    'view' => 'wired:eps',
    'rv' => 0,
    'anim' => 1,
    'print' => 1,
    'visu' => '',
    'output' => '--iso,--coord:eq'
);

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('ephemph',array($param));
  // Display the results
  if ($param['mime'] == 'text')
  {
    header("HTTP/1.0 ".$response->status);
    header("Content-Type: text/plain");
    echo "# Flag: ".$response->flag."\n";
    echo "# Ticket: ".$response->ticket."\n";
    $res = explode(';', $response->result);
    $nbr = count($res);
    $key = array_keys($res);
    for ($i=0; $i<$nbr; $i++) { echo $res[$key[$i]],"\n"; };
  }
  else
  {
    header("HTTP/1.0 ".$response->status);
    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);
}