How to do?

Miriade . ephemcc

Positional ephemerides

What about Miriade.ephemcc

Miriade.ephemcc is a service of the IMCCE's Virtual Observatory project allowing the computation of the positional ephemerides of the solar system objects: planets, major satellites, asteroids and comets.

The service can be used as a Web service and easily integrated into your own software (cf. Miriade.ephemcc main page). We propose some examples of client programs for that. The service can also be used through a Web form which allows to define your input parameters, and to submit requests. This page describes how to do with some of the input parameters of the service.

The ephemerides of planets are, by default, computed with the IMCCE's INPOP 4-D planetary theory. The ephemerides of the natural satellites are computed from various peculiar planetary solutions. The ephemerides of the asteroids and comets are computed by numerical integration of the n bodies perturbated problem (post-newtonian approximation). The dynamical properties of the asteroids are taken from the ASTORB database of the Lowell Observatory or the MPCORB database of the Minor Planet Center. The dynamical properties of the comets are taken from the COMETPRO database of the IMCCE.

The dynamical properties of asteroids and comets are updated weekly (early Monday morning). The dynamical properties of the planets and their natural satellites are updated as soon as a new solution has been made publicly available.

How to use Miriade.ephemcc service?

Several methods can be helpful:
  • use the query forms made available on the IMCCE's Solar system portal.
  • implement yourself the Miriade Web service ephemcc method into your own software (see client templates) or call the HTTP request on the command line interface using non-interactive file transfert programs such as wget or curl (see the how to consume section).
  • use the Miriade services through a VO-compliant software which implements them, such as Aladin and the Miriade plugin, or other VO applications. For example you can directly submit a request to Miriade.ephemcc in the Location entry of the File->Load Table menu of Topcat software.

How to select a Sso by its name?

The choice of a Sso can be done by its official name, or its number, or its provisional designation. For the moment, the knowledge database of Miriade does not recognize all the possible designations of Sso. In particular, historical names of asteroids, comets and natural satellites are not recognized. You must use the current designations of Sso. The nomenclature of names of Sso is defined and maintained by the Working Group for Planetary System Nomenclature (WGPSN) of the Division III of the International Astronomical Union.

The general syntaxe of Sso names in Miriade is the following:

<prefix>:<name>

where <prefix> is one of the following codes:

  • a to point out an asteroid
  • c to point out a comet
  • dp to point out a dwarf planet
  • p to point out a planet
  • s to point out a natural satellite

and where <name> is the official number or name, or the provisional designation of the Sso. The space character in the provisional designation of asteroids can be substituted by the underscore (_) or the HTML character %20.

If no prefix is used, the type of the Sso must be provided through the type argument. The list of known types is:

  • Asteroid
  • Comet
  • Dwarf planet
  • Planet
  • Satellite
The old nomenclature (aster, comet, planet, satel) is still usable.

Example:

dp:ceres, a:3834, a:1992_SZ14, 
p:mars, s:501, 
c:1P, c:P/d'Arrest

Restriction: the names of asteroids and comets must be the official names adopted by IAU. If not, they could not be recognized. You can use the SsODNet service to seek for and to resolve solar system object names. For the natural satellites, only the ones for which an ephemeris is available are recognized.

Binary asteroids: If the name of an asteroid is suffixed by /X then the differential position of its satellite (if it exists) is also computed. X must be the name of the choosen component of the asteroidal system. Example: a:kalliope/Linus allows to compute the ephemerides of the asteroid (22) Kalliope and to display the differential coordinates of its satellite named Linus. The list of asteroidal systems for which ephemerides can be computed, as well as the list of orbital solutions available for a given asteroidal system, can be obtained through the Miriade.ephemsys method and its specific interface.

How to request ephemerides for a list of Sso?

To request ephemerides of multiple Sso in a single request, you have to provide a text file (Content-Type: text/plain) containing a comma separated list of Sso designations (multi lines accepted).

Example of file:

1,2,3
4,5,6

There are two ways to submit the file of targets:

  1. HTTP request: use curl to POST the file when submitting the request. Prefix the file name with an @ sign to force the content part to be a file (c.f. curl manual), and use the key targets to introduce the file name. Example:
curl -F "targets=@<filename>" 
 "https://ssp.imcce.fr/webservices/miriade/api/ephemcc.php?<args>"
 

where <filename> is the name of the local file which contains the targets. In that case, the parameter -name must be omitted in the arguments, and the -type parameter MUST be used to specify the type of solar system objects.

  1. SOAP client: you have to store your file on a Web server, and to provide a valid URL into the name parameter of the ephemcc method, so that the Miriade server can get the file content. Use the type parameter to specify the type of solar system objects. Example (php client):
// Input parameters
$param = array('name' => 'http://my.webserver/~joe/targets.dat',
               'type' => "aster",
               ... other args ... );

Restriction: A file must contain only one type of solar system objects: planets and natural satellites or asteroids and dwarf planets or comets. A file must contain not more than 5000 targets. The designation of targets must not be preceded by the prefixed code.

How to define the computation epoch?

The epoch must be formatted as a textual english date (in accordance with the GNU syntax of dates), or as a julian day or as an ISO 8601 date.

Examples (non exhaustive) of valid dates:

  • now
  • 2006-01-27T1:53:34
  • 2453762.529467592
  • 10 September 2000
  • +1 day
  • +1 week 2 days 4 hours 2 seconds
  • next Thursday
  • last Monday

The timescale of the epoch is provided by the argument tscale. The time span for which ephemeris can be computed depends on the chosen planetary theory (argument theory, see below).

Restriction: the seconds must be an integer number in the ISO format. For a time resolution better than a second, please use the julian period.

Tolerance: the character 'T' of the ISO 8601 format can be omitted.

Limits: the time span covered by Miriade's ephemerides depends on the choosen planetary theory:

  • DE200: 1599-12-09 0h (2305424.5) to 2169-06-03 0h (2513424.5)
  • BDL82: 1599-03-28 0h (2305168.5) to 2050-01-02 0h (2469808.5)
  • DE403: 1599-12-09 0h (2305424.5) to 2199-07-24 0h (2524432.5)
  • SLP98: -100-12-28 0h (1684528.5) to 3000-03-03 0h (2816848.5)
  • DE405: 1599-12-09 0h (2305424.5) to 2200-02-01 0h (2524624.5)
  • DE406: -3000-02-23 0h (625360.5) to 3000-03-03 0h (2816848.5)
  • INPOP: 973-06-04 12h (2076601.0) to 3026-07-25 12h (2826489.0)
  • DE430: 1549-12-21 0h (2287184.5) to 2650-01-25 0h (2688976.5)
  • DE431: -13200-08-15 0h (-3100015.5) to 17191-03-15 0h (8000016.5)

How to request ephemerides for a list of epochs?

In order to request the ephemerides of Sso for multiple epochs, you have to provide a text file (Content-Type: text/plain) containing a list of epochs (one per line). The epochs can be formatted as a textual english date (in accordance with the GNU syntax of dates), as a julian day or as an ISO 8601 date. Different formats can be mixed in the same file.

Example of file (one date per line):

2456246.535046296
2456247.835046296
2456248.135046296
now
2012-11-17T12:36:12.1
2012-11-17T12:46:42.123
2012-11-17T13:26:2.15
There are two ways to submit the file of epochs:
  1. HTTP request: use curl to POST the file when submitting the request. Prefix the file name with an @ sign to force the content part to be a file, and use the key epochs to introduce the file name. In that case, the arguments -ep, -nbd and -step must be omitted. Example:
curl -F "epochs=@<filename>" 
 "https://ssp.imcce.fr/webservices/miriade/api/ephemcc.php?<args>"

where <filename> is the name of the local file which contains the epochs.

  1. SOAP client: you have to store your file on a Web server, and to provide a valid URL into the epoch parameter of the ephemcc method, so that the Miriade server can get the file content. The nbd and step parameters can not be filled. Example (php client):
// Input parameters
 $param = array('name' => 'a:Ceres',
                'type' => "",
                'epoch' => "http://my.webserver/~joe/epochs.dat"
                'nbd' => "",
                'step' => "",
                ... other args ... );

Restriction: A file must contain not more than 1000 epochs.
Tip: Ascending sort order of epochs optimizes the ephemeris computation.

How to define the coordinates of the observer?

— For a terrestrial observer, enter the IAU code of the observatory of your choice, or the code 500 for an observer located at the centre of mass of the Earth (geocenter). If the place of observation is not referenced in the database of IAU observatories, then provide the geographical coordinates formatted as a geographic location URI:
[+-]latitude, [+-]longitude, altitude
or as the less recommended free format:
[+-]longitude [+-]latitude altitude

The longitude and latitude must be expressed in decimal degrees in the WGS84 reference system, and the altitude must be expressed in meters above the mean sea level. Longitudes are negative toward West. The sign + of the longitude and latitude can be omitted. If not, use the encoding %2B instead of the symbol + which is not correctly transmitted in the URL.

Example for Paris observatory (2°20′11.4874" E, 48°50′11.32" N, 67 m):

-observer=%2B48.836477778, 2.336524278, 67.0

— For an extra-terrestrial observer, use one of the following codes recognized by Miriade:

@0 | 500@0
for an observer located at the barycenter of the Solar System
@sun | sun
for an observer located at the center of mass of the Sun
earth@L2 | 500@L2 | L2
for an observer located at the libration point L2 of the system Sun-(Earth+Moon)
venus@L2
for an observer located at the libration point L2 of the system Sun-Venus
mars@L2
for an observer located at the libration point L2 of the system Sun-Mars
jupiter@L2
for an observer located at the libration point L2 of the system Sun-Jupiter
saturn@L2
for an observer located at the libration point L2 of the system Sun-Saturn
@<planet_name>
for an observer located at the center of mass of a planet or a natural satellite. <planet_name> must be one of: Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Netpune, or one of their natural satellites recognized by Miriade.
spirit | @-254
for an observer located at the landing site of the Spirit rover, the first Nasa's Mars Exploration Rover. The areocentric coordinates of this site are λ=175.4729°E ; φ=14.5692°S in the IAU 2000 frame (Arvidson et al., Science vol. 305, 2004).
opportunity | @-253
for an observer located at the landing site of the Opportunity rover, the second Nasa's Mars Exploration Rover. The areocentric coordinates of this site are λ=354.47°E ; φ=1.95°S in the IAU 2000 frame (MER factsheet).

— For an observer onboard a spacecraft, use one of the following codes recognized by Miriade. The periods of validity of the orbit (PVO) are expressed in UTC:

cassini | @-82
for an observer onboard the Cassini spacecraft.
PVO: 2001-03-07T12:00:00 to 2006-10-19T12:00:00
galileo | @-77
for an observer onboard Galileo spacecraft.
PVO: 1995-11-20T23:58:59 to 2002-11-26T07:58:55
hst | @-48
for an observer onboard the Hubble Space Telescope.
PVO: 1990-04-25T02:00:00 to 2015-07-30T02:18:00
iso
for an observer onboard the ISO satellite.
PVO: 1995-11-17T12:36:36 to 1999-01-01T13:52:00
iss | @-125544
for an observer onboard the International Space Station.
PVO: 2008-02-08T13:00:00 to 2009-01-26T13:00:00
juno | @-61
for an observer onboard Juno spacecraft.
PVO: 2011-08-05T17:18:06 to 2018-02-21T11:39:42
kepler | @-227
for an observer onboard the Kepler spacecraft.
PVO: 2009-03-07T06:22:56 to 2018-12-31T23:58:50
rosetta | @-226
for an observer onboard the Rosetta spacecraft.
PVO: 2004-03-02T09:25:18 to 2014-08-04T01:15:00
sirtf | sst | @-79
for an observer onboard the Sptizer Space Telescope.
PVO: 2003-08-25T06:26:00 to 2017-01-01T00:03:50
voyager1 | @-31
for an observer onboard the Voyager 1 spacecraft.
PVO: 1977-09-08T09:08:17 to 1979-01-14T15:51:00
1979-04-24T07:33:03 to 1980-10-06T10:14:10
1980-12-20T16:45:20 to 2021-01-01T00:00:00
voyager2 | @-32
for an observer onboard the Voyager 2 spacecraft.
PVO: 1977-08-23T11:29:11 to 1979-05-03T21:42:56
1979-09-15T11:07:26 to 1981-07-04T11:59:00
1981-10-17T18:43:57 to 1986-01-04T11:58:00
1986-02-14T00:01:31 to 1989-08-02T10:57:30
1989-09-16T20:56:58 to 2021-01-05T00:00:00
xmm-newton | @-10
for an observer onboard the XMM-NEWTON spacecraft.
PVO: 1999 DEC 16 11:28:00 to 2016 AUG 09 13:59:41

Sources of spacecraft kernels:

How to set up filters?

In order to compute the magnitude of asteroids in various filters, you have to provide a comma-separated list of filter names:
--colors(<filter>[,<filter>,...])

where <filter> is either the filter Id or the pattern "instrument:filter" as listed in the following table. A short name (case-sensitive) is also available for a restricted list of filters. You can get more information about filters by visiting the Web site "Filter Profile Service" of the Spanish VO, or by clicking on the external link symbol of a given filter.

Examples of request:

FacilityFilter IdPatternShort nameProfile
GenericGeneric/Bessell.UBessell:U
Generic/Bessell.BBessell:B
Generic/Bessell.VBessell:V
Generic/Bessell.RBessell:R
Generic/Bessell.IBessell:I
Generic/Cousins.RCousins:R
Generic/Cousins.ICousins:I
Generic/Johnson.UJohnson:UU
Generic/Johnson.BJohnson:BB
Generic/Johnson.VJohnson:VV
Generic/Johnson.RJohnson:RR
Generic/Johnson.IJohnson:II
Generic/Johnson.JJohnson:J
Generic/Johnson.MJohnson:M
SLOAN SLOAN/SDSS.u SDSS:u u
SLOAN/SDSS.g SDSS:g g
SLOAN/SDSS.r SDSS:r r
SLOAN/SDSS.i SDSS:i i
SLOAN/SDSS.z SDSS:z z
2MASS 2MASS/2MASS.J 2MASS:J
2MASS/2MASS.H 2MASS:H
2MASS/2MASS.Ks 2MASS:Ks
ParanalParanal/VISTA.Z VISTA:Z Z
Paranal/VISTA.Y VISTA:Y Y
Paranal/VISTA.J VISTA:J J
Paranal/VISTA.H VISTA:H H
Paranal/VISTA.Ks VISTA:Ks Ks
GAIA GAIA/GAIA2r.Gbp Gaia:BP BP
GAIA/GAIA2r.G Gaia:G G
GAIA/GAIA2r.Grp Gaia:RP RP
Kepler Kepler/Kepler.K Kepler:K

How to set up thermal flux?

The computation of the thermal flux of asteroids depends on the values of the four 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

Biblio: Near-Earth Asteroid Thermal Model

How to set up PAF parameters?