Miriade

ephemph

Physical ephemerides

The method ephemph is intended to people who need to compute the apparent aspect - or physical ephemeris - of Solar system objects. See also psv method.

HTTP Request

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:
https://ssp.imcce.fr/webservices/miriade/api/ephemph.php?[parameters]
where [parameters] is a list of parameters separated by the ampersand 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> Type of the target (default: empty) Asteroid | Comet | Dwarf Planet | Planet | Satellite
-ep=<string> Requested epoch, expressed in Julian period, ISO format,
or formatted as any English textual datetime
973-06-09 12h (2076601.0) .. 3026-07-25 12h (2826489.0)
-nbd=<int> Number of dates of ephemeris to compute (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 (default: 1d) Ex.: 2.345h or 1d
-tscale=<string> Ephemeris time scale (default: UTC) UTC | TT
-observer=<string> Code or geographic coordinates of the observer's location (default: 500) Ex.: 500 (geocenter), 007 (Paris), @sun, @rosetta, ...
-so=<int> Id of the physical model (default = 1) 1 ≤ so ≤ 99
-mime=<string> Mime type of the results (default: votable) votable | html | text | text/csv | json
-output=<string> Comma separated list of options (default: blank) See section Optional parameters
-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.

HTTP Request specific interface

This interface is intended to request the list of physical models available for the computation of the physical ephemerides of solar system objects with Miriade ephemph method. This is done by using the following HTTP request:
https://ssp.imcce.fr/webservices/miriade/api/ephemph.php?-get=<keyword>[&parameters]
where keyword is one of model to request the physical models of a given object specified with -name argument, or models to query all the models of a population of objects, and where parameters are:
ParameterDefinitionLimits or value
-name=<string> The designation of a solar system object: <prefix>:<name>.
Leave the name part empty to get the physical models of all objects
of type <prefix>, e.g. -name=p: retrieves all the physical models of planets
Examples: a:22 or a:Kalliope or p:
-mime=<string> Mime type of the results, optional, default text/csv 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 (without space)

Examples: click on the following links to get:

The query returns a document containing the following information, formatted according to the given MIME type:

ParameterDefinitionUnit or Value
ssotype Type of the targetAsteroid | Planet | Satellite | Comet
ssonum Official number of the target (blank if unknown)
ssoname Name or designation of the target
ssomodel Name of the physical modelEPROC | DAMIT
ssomodelid Id of the physical model1..99
iauspin_ra Right ascension of the spin axisdeg
iauspin_dec Declination of the spin axisdeg
iauspin_w Longitude of the prime meridiandeg
iauspin_wp Rotation ratedeg/d
iauspin_tref Reference epoch of the prime meridian longitudejulian day
ssospinfile Existence of spin data according DAMIT databaseyes | no
ssoshapefile Existence of shape model according DAMIT databaseyes | no
ssoringfile Existence of ring definitionyes | no
ssofeaturefile Existence of features on the surface of the targetyes | no

To query the physical ephemerides of a solar system object with a specific physical model, use the given ID = ssomodelid 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:
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:
ephemph (inputArray)
The input parameter 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 an URL
type string - Asteroid | Comet | Dwarf Planet | Planet | Satellite none Type of the target
epoch string epoch
or URL
973-06-09 12h (2076601.0) .. 3026-07-25 12h (2826489.0) none Requested epoch (julian period, ISO format, English textual datetime), or list of epochs provided through an URL
nbd int - 1 ≤ nbd ≤ 5000 1 Number of dates of ephemeris to compute
step string d|h|m|s step ≤ 100d 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)
so int - 1 ≤ so ≤ 99 1 Physical model number
mime string - votable | html | text | text/csv | json votable Mime type of the results
output string - Comma separated list of options blank See section Optional parameters
get string - model | models blank Use this parameter (together with name and oscelem) to request specific data used by Miriade ephemph method to compute ephemerides. No ephemeris is provided.

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

Optional parameters

The optional parameters (arg. output) can be used to format the display of the date, or to add extra ephemeris data. The available parameters are:
--coord(<code>)
where <code> is one of the following value to display:
  • eq: apparent of the date equatorial coordinates
  • eq2000: astrometric J2000 equatorial coordinates
  • ec: ecliptic coordinates
  • rect: rectangular coordinates
--greg
to format the epoch as a calendar date.
--iso
to format the epoch as an ISO-8601 date (default).
--jd
to format the epoch as a julian period.
--lighttime
to display the value of the light time between the target and the observer.
--rv
to display the detailed values of radial velocity.
--ttmutc
to display the TT-UTC value.
--colors(<filter>[,<filter>,...])
to compute the magnitude of the target for listed filters (asteroids only). See section How to set up magnitude filters.
--thermalflux(λ,pv,η,ε)
to compute the thermal flux of the target (asteroids only) using the Near-Earth Asteroid Thermal Model (NEATM) implemented by the Lagrange laboratory (OCA) and IMCCE. See section How to set up thermal flux.

Query examples

Output results

The output parameters of the ephemph method are described in the following table. Columns with italicized numbers are present only when the corresponding option is enabled.

Col. Definition Units Format Option Note
1 Object name - String (1)
2 Gregorian Date or Julian period datetime or day ISO-8601 or decimal (2,3)
3 TT-UTC value s decimal --ttmutc (3)
4, 5 Sub-Earth point longitude and latitude degree decimal (4)
6, 7 Sub-Solar point longitude and latitude degree decimal (4)
8 North pole position angle w.r.t. celestial north pole degree decimal
9 Angular distance between the pole and the center of the body degree decimal
10 Visual magnitude - decimal
11‑40 Magnitudes for requested filters mag decimal --colors() (5,3)
41 Thermal flux for requested wavelengths Jy decimal ‑‑thermalflux() (6,3)
42 Phase angle degree decimal
43 Target apparent angular radius arcsec decimal
44 Range to observer AU decimal
45 Light time between the target and observer min decimal --lighttime (3)
46 Target heliocentric distance AU decimal
47 Angle of position of the equator of intensity degree decimal
48 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
49 Radial velocity (RV) of target center w.r.t. observer km/s decimal
50 Radial velocity (RVc) of target center corrected for the radial velocity of the observer (BERV) and increased by its velocity toward the Sun (RVs): RVc = RV-BERV+RVs km/s decimal --rv (3)
51 Projection of the barycentric velocity vector of the observer along the observer-target direction (BERV) km/s decimal --rv (3)
52 Projection of the heliocentric velocity vector of the target along the heliocentric direction of the target (RVs) km/s decimal --rv (3)
53 X coordinate of the differential position of the component w.r.t. the primary arcsec decimal <system>/<component> (7)
54 Y coordinate of the differential position of the component w.r.t. the primary arcsec decimal <system>/<component> (7)
55, 56, 57 Equatorial or ecliptic coordinates, in spherical or rectangular format hour (RA), degree (DEC, Long, Lat), au (x,y,z), au/d (vx,vy,vz) sexagesimal or decimal --coord() (3)

Notes:

  1. This column does not exist when the mime type is set to text.
  2. By default the date is expressed in the ISO-8601 format. It can be changed to julian period or calendar date with the output argument.
  3. See Optional parameters section.
  4. The sub-Earth and sub-Solar point are expressed in the system defined by argument so.
  5. The columns 11-40 display the asteroid magnitudes for each requested filter provided through the --colors() option.
  6. The column 41 displays the asteroid thermal flux for each requested wavelength provided through the --thermalflux() option. The flux are formatted as a list of values between brackets, e.g. {f1; f2; ...}.
  7. The columns 36-38 display the differential position of the component of an asteroidal multiple system, defined by its name as <system>/<component>, e.g. name=a:kalliope/linus. See the HOWTO section for a full description about how to name targets.

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 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:ceres',
               'type' => "",
               'epoch' => now,
               'nbd' => 5,
               'step' => '1d',
               'tscale' => 'UTC',
               'so' => 1,
               'gensol' => '',
               'observer' => '500',
               'target' => '',
               'mime' => 'text',
               'output' => '--rv,--lighttime',
               'get' => ''
);

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('ephemph',array($param));
   // Display the results
   if (! empty($param['get'])) 
   {
      switch ($param['mime']) {
        case 'text':
          $contentType = "Content-Type: text/plain";
          $contentDisposition = null;
          break;
        case 'text/csv':
          if ($response->status < 300) {
            $contentType = "Content-Type: text/csv";
            $contentDisposition = 'Content-disposition: attachment;filename="physical_params.csv"'; 
          } else {
            $contentType = "Content-Type: text/plain";
            $contentDisposition = null;
          }
          break;
        case 'json':
          $contentType = "Content-Type: application/json";
          $contentDisposition = null;
          break;
        case 'html':
        case 'votable':
          $contentType = "Content-Type: text/xml;content=x-votable";
          $contentDisposition = null;
          break;
      }
      header("HTTP/1.0 ".$response->status);
      header($contentType);
      if (! is_null($contentDisposition)) { header($contentDisposition); }
      echo $response->result.PHP_EOL;
   }
   else 
   {
      // Display 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="ephemph.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);
}