API docs by Redocly

OPALE API (20250228.0)

Download OpenAPI specification:Download

OPALE API: no-reply@imcce.fr URL: https://opale.imcce.fr/ License: Terms of Service

OPALE provides a catalog of APIs to fetch the ephemerids data

Status of the service

Get the status of the service.

Example: https://opale.imcce.fr/api/status

Responses

Response samples

Content type
application/json
{
  • "apiVersion": "2025.02.28",
  • "description": "Opale API service 2025.02.28 is available and is running the library version 2025.2.5",
  • "libraryVersion": "2025.2.5",
  • "status": "OK"
}

Eclipses of the Moon or the Sun

Get all lunar or solar eclipses for an optional given date. If the date is not provided, the eclipses of the current year are returned. The instants of the events are given in the timescale UTC for the dates after 1962 and UT1 for the dates before 1962.

A response, which contains the information about the eclipses, is returned to the client encoded in json format, by default. A map of the visibility of the eclipse on the Earth is streamed to the client if the header Accept of the request specifies the MIME media types image/svg+xml, application/pdf or application/postscript and the date is a calendar day. This behavior can be replaced by the query parameter format.

Examples:

Capabilities : https://opale.imcce.fr/api/v1/phenomena/eclipses/capability

path Parameters
body
required
integer
Enum: 10 301
Example: 301

NAIF identification number of the body.

  • 10 for solar eclipse
  • 301 for lunar eclipse
required
Year (string) or Calendar date (string)
Example: 2025

Filter by year or day.

The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.

If the calendar is not given, then date is assumed to be expressed in the (proleptic) gregorian calendar.

query Parameters
nbd
integer [ 1 .. 10 ]
Default: 1
Example: nbd=1

Number of years to compute

NAIF Identification (integer) or observatory code (string) or Array of (geodetic latitude, longitude, and optionally the altitude) (numbers)

Location of the observer. General circumstances of the solar eclipses are computed (default case) if the observer is located at the geocenter, otherwise, local circumstances are computed. This parameter is ignored for the lunar eclipses.

format
string
Default: "json"
Enum: "json" "image" "video"
Example: format=json

The response format. The default response format is given by the header request Accept. If format is given, the header request Accept is ignored. If the format is image, the image bytes are directly streamed to the client.

image-format
string
Default: "svg"
Enum: "svg" "eps" "pdf"
Example: image-format=svg

The format of the exported image. The default format of the exported image is svg.

video-format
string
Default: "mp4"
Enum: "hls" "mp4" "webm"
Example: video-format=mp4

The format of the exported video. The default format of the exported video is mp4.

video-definition
string
Default: "HD"
Enum: "custom" "SD" "HD" "FHD"
Example: video-definition=HD

The definition of the exported video. The default definition of the exported video is HD.

  • custom : the resolution is given by the parameter image-size.
  • SD : the number of lines of video is set to 576. The width of the video is adjusted in order to respect the projection.
  • HD : the number of lines of video is set to 720. The width of the video is adjusted in order to respect the projection.
  • FHD : the number of lines of video is set to 1080. The width of the video is adjusted in order to respect the projection.
Array of integers or strings = 2 items
Default: [800,600]
Example: image-size=800,600

The size (width , height) of the exported image in pixels. The default size of the export image is (800,600). If one component is auto, then its size in pixels is automatically set to maximize the visible world depending of the projection.

image-style
string
Default: "ssp"
Enum: "ssp" "newsletter"
Example: image-style=ssp

The style of the exported image. The default style of the export image is ssp.

map-projection
string
Default: "EPSG:3395"
Enum: "EPSG:3395" "EPSG:3857" "EPSG:9840" "EPSG:9820" "EPSG:9825" "ESRI:54026"
Example: map-projection=EPSG:3395

The projection of the map. The default projection is the Mercator conformal projection (EPSG:3395).

  • EPSG:3395 : Mercator conformal projection
  • EPSG:3857 : Web-Mercator or pseudo-Mercator projection
  • EPSG:9820 : Lambert Azimuthal Equal Area
  • EPSG:9825 : Pseudo Plate Carree
  • EPSG:9840 : Orthographic projection
  • ESRI:54026 : Stereographic projection
map-center
Array of numbers = 2 items [ items [ -180 .. 180 ] ]
Default: [0,0]
Example: map-center=0,0

The geodetic longitude and latitude of the center of the projection of the map, expressed in decimal degrees. The longitude is the first argument and the latitude is the second argument.

map-theme
string
Default: "land-small"
Enum: "land-small" "land-medium" "country-small" "country-medium"
Example: map-theme=land-small

The background theme of the map. The default content include the lands and major islands. Images produced with the theme '-small' have a size in bytes smaller than those generated with '-medium'.

  • land-small : show the lands and major islands. Suitable for schematic map of the eclipse
  • land-medium : show the lands and major islands. Suitable for detailed map of the eclipse
  • country-small : show the country boundaries. Suitable for schematic map of the eclipse
  • country-medium : show the country boundaries. Suitable for detailed map of the eclipse
map-zoom
number [ 1 .. 20 ]
Default: 1
Example: map-zoom=1

The zoom level. The lowest level 1 is the lowest zoom level (fully zoomed out) and 20 is the highest level (fully zoomed in). The zoom level determines how much of the world is visible on a map.

map-labels
string
Default: "none"
Enum: "none" "en" "fr"
Example: map-labels=none

Display the label of the lines of the events on the map.

  • none : no label is displayed.
  • en : english labels (P1, U1, U2, U3, U4, P4) are displayed.
  • fr : french labels (P1, O1, T1, T2, O2, P2) are displayed.
map-meridian-zenith
boolean
Default: false
Example: map-meridian-zenith=false

Show, as a solid line on the map, the meridian where the moon is at the zenith at the greatest event.

Responses

Response samples

Content type
{
  • "link": {},
  • "request": {
    },
  • "response": {
    }
}

Rise, transits and set

Get all rise, transits, and set of a body for an given date and location. The instants of the events are given in the timescale UTC for the dates after 1962 and UT1 for the dates before 1962.

A response, which contains the information about the rise, transits and set, is returned to the client encoded in json format. The date of the twilight are provided only for the Sun.

The effect of the refraction of the atmosphere is taken into account for the computation of the date of the rise and set. The center of the apparent disk of the body is used to compute the rise, transits and set.

The elevation of the body during the transit is :

  • apparent elevation if the value is positive or zero, the object is visible taking into account the refraction of the atmosphere.
  • true elevation, otherwise, the object is invisible, even taking into account the refraction of the atmosphere.

If the position of the center of a planet is not available for a requested time, as no satellites theory is available at that requested time, then the position of the barycenter of the planetary system is used for the computation of the position of the planet.

Examples:

Capabilities : https://opale.imcce.fr/api/v1/phenomena/rts/capability

path Parameters
body
required
string^\d{1,9}|HIP-\d{1,6}$
Default: "10"
Example: 10

Observed body:

  • NAIF identification number of the observed body (list)
  • identifier of an observed star : HIP number, WDS identifier.

example:

  • 4 for Mars
  • HIP-49669 for Regulus.
date
required
string^(gregorian,|julian,)?-?\d{4}-(0?[1-9]|1[0-2]...
Default: "2020-01-10"
Example: 2025-01-10

Requested calendar date YYYY-MM-DD. The calendar of this date is given by the prefix value. If the prefix value is missing, the date is assumed to be expressed in the (proleptic) gregorian calendar. The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.
required
observatory code (string) or Array of (geodetic latitude, longitude, and optionally the altitude) (numbers)
Example: 48,150,0

Location of the observer on the Earth

query Parameters
step
integer [ 1 .. 100 ]
Default: 1
Example: step=1

Step between the dates to compute, expressed in day

nbd
integer [ 1 .. 730 ]
Default: 1
Example: nbd=1

Number of dates to compute

twilight
boolean
Default: false
Example: twilight=false

Provide or not the dawn and dusk timings for the Sun. For other bodies, this boolean value is ignored.

group-by
string
Default: "body-calendarDate"
Value: "body-calendarDate"
Example: group-by=body-calendarDate

Group the results into different arrays according different orders.

  • body-calendarDate : The results are grouped by body and then grouped by the same calendar day.
timescale
required
string (timescale) ^(UTC([\+-][01][0-9]:[0-5][0-9])?)|(UT1)$
Default: "UTC"

If date is before the year 1962, then all dates and times are expressed in the timescale UT1 and the value of this field is ignored. After the year 1962, all dates and times of the request or response are expressed in this timescale.

The supported timescales are

  • UTC
  • UTC±hh:mm , where ±hh:mm is the difference in hours and minutes from UTC. The plus sign math symbol, in the character ±, must be encoded using the characters %2B.
  • UT1

For all dates expressed in UTC or UTC±hh:mm after the last leap second, the difference between the timescale UTC and TAI is constant.

The timescale UT1 is computed using the EOP series C04 when they are available. Before and after the EOP series, UT1 is adjusted using splines and parabola to the available observations.

Responses

Response samples

Content type
application/json
{
  • "link": {},
  • "request": {
    },
  • "response": {
    }
}

Phenomena of natural satellites

Get the phenomena of satellites of the planets Jupiter, Saturn, Uranus and Arecibo for a geocentric observer. It computes the mutual phenomena of the satellites ( eclipses and occultations ) and the phenomena between the satellites and the planet ( eclipse, occultation, transit and shadow ).

The predicted instants are the instant of the first and last contact ('speck') of the phenomena.

The list of phenomena is returned to the client encoded in json format.

Examples :

path Parameters
body
required
integer
Enum: 599 699 799 920004337
Example: 599

NAIF identification number of the observed body (list)

query Parameters
required
number or string

First date of the result. The timescale of this date is given by the timescale. The calendar of this date is given by the parameter calendar.

nbd
integer [ 1 .. 730 ]
Default: 1
Example: nbd=1

Number of dates to compute

calendar
string (calendar)
Default: "gregorian"
Enum: "gregorian" "julian" "JD"
Example: calendar=gregorian

All dates and times of the request or response are expressed in this calendar.

The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.
  • JD : Julian date or day. The Julian Date (JD) of any instant is the Julian day number for the preceding noon plus the fraction of the day since that instant. It follows the resolution B1 of the XXIIIrd IAU General Assembly.
timescale
string (timescale) unique
Default: "UTC"
Enum: "TT" "UTC" "UT1"
Example: timescale=UTC

All dates and times of the request or response are expressed in this timescale.

Before the January 1st 1961 0h UTC, the difference between the timescale UTC and TAI is constant and equals to 0. For all dates expressed in UTC after the last leap second, the difference between the timescale UTC and TAI is constant.

The timescale UT1 is computed using the EOP series C04 when they are available. Before and after the EOP series, UT1 is adjusted using splines and parabola to the available observations.

theory
Array of strings (theory) non-empty unique
Default: ["INPOP19A","NOE-4-2020","NOE-5-2021","SAI-5-2021","NOE-6-2018","SAI-6-2021","PHOEBE-2020","NOE-7-2013","SAI-7-2021","SAI-8-2015","SAI-8-2021","ASTMOONS-2025"]
Items Enum: "DE441" "INPOP19A" "NOE-4-2020" "MAR097" "NOE-5-2021" "SAI-5-2021" "JUP365" "JUP344" "NOE-6-2018" "SAI-6-2021" "PHOEBE-2020" "SAT368" "SAT393" "SAT427" "SAT428" "SAT441" "SAT450" "NOE-7-2013" "SAI-7-2021" "URA111" "URA112" "URA115" "URA116" "SAI-8-2015" "SAI-8-2021" "NEP086" "NEP095" "ASTMOONS-2025"
Example: theory=INPOP19A

Planetary and satellites theories used for the computations (details)

Responses

Response samples

Content type
application/json
{
  • "link": {},
  • "request": {
    },
  • "response": {
    }
}

Moon phases

Get all moon phases phenomena for a given date. The instants of the events are given in the timescale UTC by default.

A response, which contains the information about all phenomena, is returned to the client encoded in json format.

Examples:

Capabilities : https://opale.imcce.fr/api/v1/phenomena/moonphases/capability

query Parameters
year
required
integer
Default: 2022
Example: year=2022

Requested calendar year with format YYYY

month
integer [ 1 .. 12 ]

Requested calendar month with format MM

timescale
required
string (timescale) ^(UTC([\+-][01][0-9]:[0-5][0-9])?)|(UT1)$
Default: "UTC"

All dates and times of the request or response are expressed in this timescale.

The supported timescales are

  • UTC
  • UTC±hh:mm , where ±hh:mm is the difference in hours and minutes from UTC. The plus sign math symbol, in the character ±, must be encoded using the characters %2B.
  • UT1

Before the January 1st 1961 0h UTC, the difference between the timescale UTC and TAI is constant and equals to 0. For all dates expressed in UTC after the last leap second, the difference between the timescale UTC and TAI is constant.

The timescale UT1 is computed using the EOP series C04 when they are available. Before and after the EOP series, UT1 is adjusted using splines and parabola to the available observations.

calendar
required
string (calendar)
Default: "gregorian"
Enum: "gregorian" "julian"
Example: calendar=gregorian

All dates and times of the request or response are expressed in this calendar.

The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.

Responses

Response samples

Content type
application/json
{
  • "link": {},
  • "request": {
    },
  • "response": {
    }
}

Equinoxes and Solstices

Get all equinoxes and solstices on the Earth and on the planet Mars over a given timespan. The instants of the events are given in the timescale UTC by default. The reported phenomena corresponds to the nothern hemisphere of the planet. The equinoxes and solstices on the planet Mars corresponds to the values 0°, 90°, 180°, and 270° of the apparent planetocentric orbital longitude (L_s) of the Sun from the vernal equinox of the body and their instants are corrected using the light-time correction between the planet and an observer located at the geocenter.

A response, which contains the information about all phenomena, is returned to the client encoded in json format.

If the position of the center of the planet Mars is not available for a requested time, as no satellites theory is available at that requested time, then the position of the barycenter of the Mars and its satellites is used for the computation of the position of the planet.

Examples:

path Parameters
body
required
integer
Default: 399
Enum: 399 499
Example: 399

NAIF identification number of the planet (list) :

  • 399 for the Earth
  • 499 for the planet Mars.
query Parameters
year
required
integer
Default: 2022
Example: year=2022

Requested calendar year with format YYYY

timescale
required
string (timescale) ^(UTC([\+-][01][0-9]:[0-5][0-9])?)|(UT1)$
Default: "UTC"

All dates and times of the request or response are expressed in this timescale.

The supported timescales are

  • UTC
  • UTC±hh:mm , where ±hh:mm is the difference in hours and minutes from UTC. The plus sign math symbol, in the character ±, must be encoded using the characters %2B.
  • UT1

Before the January 1st 1961 0h UTC, the difference between the timescale UTC and TAI is constant and equals to 0. For all dates expressed in UTC after the last leap second, the difference between the timescale UTC and TAI is constant.

The timescale UT1 is computed using the EOP series C04 when they are available. Before and after the EOP series, UT1 is adjusted using splines and parabola to the available observations.

calendar
required
string (calendar)
Default: "gregorian"
Enum: "gregorian" "julian"
Example: calendar=gregorian

All dates and times of the request or response are expressed in this calendar.

The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.
nbd
integer [ 1 .. 1000 ]
Default: 1
Example: nbd=1

The number of years to compute

Responses

Response samples

Content type
application/json
{
  • "link": {},
  • "request": {
    },
  • "response": {
    }
}

Positions

Compute the positions for a body at a given location and at regularly spaced interval of time. The dates are expressed in the timescale specified by the parameter timescale.

A response, which contains the information about the requested position, is returned to the client encoded in json or text format.

If the position of the center of a planet is not available for a requested time, as no satellites theory is provided or is available at that requested time, then the position and velocity of the barycenter of the planetary system is used for the computation of the position and velocity of the center of mass of the planet.

Examples:

Capabilities : https://opale.imcce.fr/api/v1/positions/capability

path Parameters
body
required
string^\d{1,9}|HIP-\d{1,6}$
Default: "10"
Example: 10

Observed body:

  • NAIF identification number of the observed body (list)
  • identifier of an observed star : HIP number, WDS identifier.

example:

  • 4 for Mars
  • HIP-49669 for Regulus.
query Parameters
required
Reference axis (string) or NAIF identification number (integer)

The axis or point used as the origin of the absolute or relative coordinates.

Absolute coordinates are computed if the reference is origin. Relative coordinates (e.g., tangential coordinates, elongation, ...) are computed if the reference is a celestial body.

required
number or string

First date of the result. The timescale of this date is given by the timescale. The calendar of this date is given by the parameter calendar.

timescale
string (timescale) unique
Default: "UTC"
Enum: "TT" "UTC" "UT1"
Example: timescale=UTC

All dates and times of the request or response are expressed in this timescale.

Before the January 1st 1961 0h UTC, the difference between the timescale UTC and TAI is constant and equals to 0. For all dates expressed in UTC after the last leap second, the difference between the timescale UTC and TAI is constant.

The timescale UT1 is computed using the EOP series C04 when they are available. Before and after the EOP series, UT1 is adjusted using splines and parabola to the available observations.

calendar
string (calendar)
Default: "gregorian"
Enum: "gregorian" "julian" "JD"
Example: calendar=gregorian

All dates and times of the request or response are expressed in this calendar.

The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.
  • JD : Julian date or day. The Julian Date (JD) of any instant is the Julian day number for the preceding noon plus the fraction of the day since that instant. It follows the resolution B1 of the XXIIIrd IAU General Assembly.
step
required
string (step_string) ^[0-9]+(\.[0-9]{0,2})?[DHMS]$
Default: "1D"

Step between the dates to compute, expressed in day, hour, minute or second. The suffix letter may be :

  • D : day
  • H : hour
  • M : minute
  • S : second
nbd
integer [ 1 .. 10000 ]
Default: 1
Example: nbd=1

Number of dates to compute.

required
observatory code (string) or Array of (geodetic latitude, longitude, and optionally the altitude) (numbers) or NAIF Identification (integer)

Location of the observer.

frame
string (frame) unique
Default: "BCRF"
Enum: "BCRF" "GCRF" "TrueOfDate" "MeanJ2000" "EclipticJ2000" "EclipticTrueOfDate" "BodyFixed" "GTRF" "LocalCelestiodeticENU"
Example: frame=BCRF

Reference frame. The coordinates are expressed in this frame.

  • BCRF : Barycentric Celestial Reference Frame; origin is the Solar System Barycenter, axes are aligned with International Celestial Reference Frame ; origin is the solar system barycenter.
  • GCRF : Geocentric Celestial Reference Frame; origin is the Earth's center of mass, axes are aligned with International Celestial Reference Frame.
  • TrueOfDate : XY plane is the true equator of date, origin of longitudes is the equinox of date ; origin is the center of mass of the body.
  • MeanJ2000 : Mean Equinox/Mean Equator J2000; XY plane is the mean equator J2000 ; origin is the center of mass of the body.
  • EclipticJ2000 : Mean Equinox/Mean Ecliptic J2000; XY plane is the mean ecliptic J2000 ; origin is the center of mass of the body
  • EclipticTrueOfDate : XY plane is the ecliptic of date, origin of longitudes is true equinox of date ; origin is the center of mass of the body
  • BodyFixed : XY plane is the equator of the body, origin of longitudes is the first meridian ; origin is the center of mass of the body. The surface of the body is fixed in this frame. This frame rotates with the associated body.
  • GTRF : the Geocentric Terrestrial Reference Frame, same as BodyFixed for the Earth.
  • LocalCelestiodeticENU : Frame associated to a position near the surface of a body ; The origin of the frame is at the defining celestiodetic point location. Z axis towards Zenith direction is normal to the ellipsoid. XY axis in the local horizontal plane (normal to zenith direction). Y axis is following the local meridian towards North.

The precession/nutation model IAU2000A and EOP series C04 are applied to the frames affected by the precession and nutation, such as TrueOfDate or BodyFixed.

theory
Array of strings (theory) non-empty unique
Default: ["INPOP19A","NOE-4-2020","NOE-5-2021","SAI-5-2021","NOE-6-2018","SAI-6-2021","PHOEBE-2020","NOE-7-2013","SAI-7-2021","SAI-8-2015","SAI-8-2021","ASTMOONS-2025"]
Items Enum: "DE441" "INPOP19A" "NOE-4-2020" "MAR097" "NOE-5-2021" "SAI-5-2021" "JUP365" "JUP344" "NOE-6-2018" "SAI-6-2021" "PHOEBE-2020" "SAT368" "SAT393" "SAT427" "SAT428" "SAT441" "SAT450" "NOE-7-2013" "SAI-7-2021" "URA111" "URA112" "URA115" "URA116" "SAI-8-2015" "SAI-8-2021" "NEP086" "NEP095" "ASTMOONS-2025"
Example: theory=INPOP19A

Planetary and satellites theories used for the computations (details)

places
string (places) unique
Default: "astrometric"
Enum: "geometric" "astrometric" "apparent"
Example: places=astrometric

Applied corrections to compute the positions of the celestial bodies and the observer.

  • geometric : The position of the observed body and the position of the observer are computed at the same date of the observation. No light-time correction is applied.
  • astrometric : The position of the observer is computed at the date of the observation and the position of the observed body is computed at the different time using the light-time correction.
  • apparent : The apparent place of the observed body represents the position of the celestial body as it would be seen for the observer at the requested dates. The positions of the observer and the observed body are computed using the following corrections : light-time, relativistic light-deflection, aberrations of light. The atmosphere of the observer is assumed to be transparent and non-refracting.
format
string (format) unique
Default: "json"
Enum: "json" "text"
Example: format=json

The response format. The default response format is given by the header request Accept. If format is given, the header request Accept is ignored.

coord-format
string (coord-format)
Default: "dec"
Enum: "dec" "sexa"
Example: coord-format=dec

Coordinates (angles, ...) of the response are expressed in decimal or in sexagesimal.

  • dec : decimal angles
  • sexa : sexagesimal angles.
distance-unit
string (distance-unit) unique
Default: "Km"
Enum: "Km" "AU"
Example: distance-unit=Km

Distances of the response are expressed in Km or in AU.

quantities
Array of strings (quantities) non-empty unique
Default: ["cart"]
Items Enum: "cart" "radec" "lonlat" "lhadec" "azel" "dist" "tancart" "tanaz" "deltaradec" "el" "pan" "par" "sspa" "sopc" "sopg" "sopd" "sspc" "sspg" "sspd" "am" "angdiam" "il" "mag" "phase" "Ls" "lt" "era" "eqe" "eqo" "eqt" "lst" "TT-TDB" "TT-UT1"
Example: quantities=cart,radec,dist

Computed quantities of the observed body.

  • am : Relative air mass, ratio of absolute air masses at direction target relative to that at zenith. That quantity is stored in airMass.
  • angdiam : Apparent equatorial angular diameter of the body, as if the body were visible to the observer and fully illuminated by the Sun. That quantity is stored in angDiameter.
  • cart : absolute cartesian coordinates, expressed in frame. These coordinates are stored in cartX, cartY and cartZ.
  • radec : absolute equatorial coordinates (right ascension and declination), expressed in frame. These coordinates are stored in RA and DEC.
  • lonlat : absolute ecliptic coordinates (longitude and latitude), expressed in frame. These coordinates are stored in longitude and latitude.
  • hadec : absolute local hour angle and declination coordinates, expressed in the equatorial frame of the observer. These coordinates are stored in HA and DEC.
  • azel : local coordinates (azimuth and elevation), expressed in the local tangent frame to the ellipsoid. The azimuth is computed from the North. These coordinates are stored in azimuth and elevation.
  • dist : distance between the observed body and the observer. That coordinate is stored in distance.
  • tancart : tangent cartesian coordinates to the celestial sphere, relative to the reference. The Y-axis is in the direction to the 'north' pole of the frame and the X-axis is in the direction to the East (increasing right ascension). These coordinates are stored in X and Y.
  • tanaz : tangent coordinates (separation and position angle) to the celestial sphere, relative to the reference. The position angle is computed from the Y-axis. These coordinates are stored in S and positionAngle.
  • deltaradec : relative equatorial coordinates (right ascension and declination) to the reference, expressed in frame. These coordinates are stored in deltaRA and deltaDEC.
  • el : elongation between the observed body and the reference seen by the observer. That coordinate is stored in elongation.
  • il : illuminated fraction of a body. The body is illuminated by the Sun. That quantity is stored in illuminatedFraction.
  • mag : observed apparent visual magnitude. That quantity is stored in magnitude.
  • pan : position angle of the north pole of the body. That quantity is stored in PAn.
  • par : parallactic angle of the body. That quantity is stored in parallactic.
  • phase : observed phase of the body, illuminated by the Sun. That quantity is stored in phase.
  • sopc : Planetocentric coordinates (longitude and latitude) of the sub-observer point, expressed in the frame of the observed body (XY plane is the equator of the observed body, origin of longitudes is its first meridian). These coordinates are stored in sopcLongitude and sopcLatitude.
  • sopg : planetographic coordinates (longitude and latitude) of the sub-observer point, expressed in the frame of the observed body (XY plane is the equator of the observed body, origin of longitudes is its first meridian, the direction of the longitudes depends on the body). These coordinates are stored in sopgLongitude and sopgLatitude.
  • sopd : Planetodetic coordinates (longitude and latitude) of the sub-observer point, expressed in the frame of the observed body (XY plane is the equator of the observed body, origin of longitudes is its first meridian). These coordinates are stored in sopdLongitude and sopdLatitude.
  • sspa : Position angle of the subsolar point of the body from the Celestial North. That coordinate is stored in sspa.
  • sspc : Planetocentric coordinates (longitude and latitude) of the sub-solar point, expressed in the frame of the observed body (XY plane is the equator of the observed body, origin of longitudes is its first meridian). These coordinates are stored in sopcLongitude and sopcLatitude.
  • sspg : Planetographic coordinates (longitude and latitude) of the sub-solar point, expressed in the frame of the observed body (XY plane is the equator of the observed body, origin of longitudes is its first meridian, the direction of the longitudes depends on the body). These coordinates are stored in sspgLongitude and sspgLatitude.
  • sspd : Planetodetic coordinates (longitude and latitude) of the sub-solar point, expressed in the frame of the observed body (XY plane is the equator of the observed body, origin of longitudes is its first meridian). These coordinates are stored in sspdLongitude and sspdLatitude.
  • Ls : Apparent longitude of the Sun for the body, expressed in the orbital plane of the body and with the origin of the longitude at the equinox direction of the body. Values of Ls of 0°, 90°, 180° and 270° correspond to the northern hemisphere spring equinox, northern summer solstice, northern autumnal equinox, and northern winter solstice for the planet. That coordinate is stored in Ls.
  • lt : light-time from the observed body to the observer. That coordinate is stored in lightTime.
  • era : Earth Rotation Angle. That coordinate is stored in ERA.
  • eqe : Equation of the equinoxes. That coordinate is stored in EQE.
  • eqo : Equation of the origins. That coordinate is stored in EQO.
  • eqt : Equation of Time. That coordinate is stored in EQT.
  • lst : Local sidereal time of the observer. That coordinate is stored in LST.
  • TT-TDB : Difference between the time TT and TDB (=TT-TDB). That coordinate is stored in TT-TDB.
  • TT-UT1 : Difference between the time TT and UT1 (=TT-UT1). That coordinate is stored in TT-UT1.
theme
string (theme) unique
Default: "default"
Enum: "default" "dynastvo"
Example: theme=dynastvo

Predefined styles of outputs and computed quantities.

  • default : default theme
  • dynastvo : theme for the dynastvo services.
extraprecision
integer [ 0 .. 3 ]
Default: 0
Example: extraprecision=1

Number of additional digits for the distances and angles in the response. The computation are always done using the same precision (double-precision) but the number of digits of the floating-point numbers in the response may be changed using this parameter.

Responses

Response samples

Content type
application/json
{
  • "link": {},
  • "request": {
    },
  • "response": {
    }
}

Positions

Compute the positions for a body at a given location and at evenly spaced interval of time. The set of dates are provided in the body request and expressed in the timescale specified by the parameter timescale.

If the position of the center of a planet is not available for a requested time, as no satellites theory is provided or is available at that requested time, then the position and velocity of the barycenter of the planetary system is used for the computation of the position and velocity of the center of mass of the planet.

A response, which contains the information about the requested position, is returned to the client encoded in json or text format.

Capabilities : https://opale.imcce.fr/api/v1/positions/capability

Request Body schema: application/json
required
NAIF identification number (integer) or Observed body: - NAIF identification number of the observed body ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html)) - identifier of an observed star : HIP number, WDS identifier. example: - 4 for Mars - HIP-49669 for Regulus. (string)

Observed body:

  • NAIF identification number of the observed body (list)
  • identifier of an observed star : HIP number, WDS identifier.

example:

  • 4 for Mars
  • HIP-49669 for Regulus.
required
observatory code (string) or Array of (geodetic latitude, longitude, and optionally the altitude) (numbers) or NAIF Identification (integer)

Location of the observer.

Types of observers :

  • case of observer's location is at an Observatory, given by its IAU/MPC observatory code (list). Example : "observer": "obscode:007"

  • case of observer's location is at the center of the celestial body given by its NAIF identification number (list)
    Example : "observer": 599

  • case of terrestrial observer's location given by a GeoJson point (geodetic coordinates). Coordinates of the point on the Earth (longitude, latitude and optionally the altitude). Example : "observer": [48.8534,2.3488,39]

required
Reference axis (string) or NAIF identification number (integer)

The axis or point used as the origin of the absolute or relative coordinates.

Absolute coordinates are computed if the reference is origin. Relative coordinates (e.g., tangential coordinates, elongation, ...) are computed if the reference is a celestial body.

required
Array of numbers or Calendar date (string) [ 1 .. 10000 ] items

Set of dates of the result. This date is expressed using the standard ISO8601: YYYY-MM-DDTHH:MM:SS.SSS or using Julian Day format . The timescale of this date is given by the timescale.

frame
string (frame) unique
Default: "BCRF"
Enum: "BCRF" "GCRF" "TrueOfDate" "MeanJ2000" "EclipticJ2000" "EclipticTrueOfDate" "BodyFixed" "GTRF" "LocalCelestiodeticENU"

Reference frame. The coordinates are expressed in this frame.

  • BCRF : Barycentric Celestial Reference Frame; origin is the Solar System Barycenter, axes are aligned with International Celestial Reference Frame.
  • GCRF : Geocentric Celestial Reference Frame; origin is the Earth's center of mass, axes are aligned with International Celestial Reference Frame.
  • TrueOfDate : XY plane is the true equator of date, origin of longitudes is the equinox of date
  • MeanJ2000 : Mean Equinox/Mean Equator J2000; XY plane is the mean equator J2000.
  • EclipticJ2000 : Mean Equinox/Mean Ecliptic J2000; XY plane is the mean ecliptic J2000.
  • EclipticTrueOfDate : XY plane is the ecliptic of date, origin of longitudes is true equinox of date.
  • BodyFixed : XY plane is the equator of the body, origin of longitudes is the first meridian ; origin is the center of mass of the body. The surface of the body is fixed in this frame. This frame rotates with the associated body.
  • GTRF : the Geocentric Terrestrial Reference Frame, same as BodyFixed for the Earth.
  • LocalCelestiodeticENU : Frame associated to a position near the surface of a body ; The origin of the frame is at the defining celestiodetic point location. Z axis towards Zenith direction is normal to the ellipsoid. XY axis in the local horizontal plane (normal to zenith direction). Y axis is following the local meridian towards North.
timescale
string (timescale) unique
Default: "UTC"
Enum: "TT" "UTC" "UT1"

All dates and times of the request or response are expressed in this timescale.

Before the January 1st 1961 0h UTC, the difference between the timescale UTC and TAI is constant and equals to 0. For all dates expressed in UTC after the last leap second, the difference between the timescale UTC and TAI is constant.

The timescale UT1 is computed using the EOP series C04 when they are available. Before and after the EOP series, UT1 is adjusted using splines and parabola to the available observations.

calendar
string (calendar)
Default: "gregorian"
Enum: "gregorian" "julian" "JD"

All dates and times of the request or response are expressed in this calendar.

The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.
  • JD : Julian date or day. The Julian Date (JD) of any instant is the Julian day number for the preceding noon plus the fraction of the day since that instant. It follows the resolution B1 of the XXIIIrd IAU General Assembly.
theory
Array of strings (theory) non-empty unique
Default: ["INPOP19A","NOE-4-2020","NOE-5-2021","SAI-5-2021","NOE-6-2018","SAI-6-2021","PHOEBE-2020","NOE-7-2013","SAI-7-2021","SAI-8-2015","SAI-8-2021","ASTMOONS-2025"]
Items Enum: "DE441" "INPOP19A" "NOE-4-2020" "MAR097" "NOE-5-2021" "SAI-5-2021" "JUP365" "JUP344" "NOE-6-2018" "SAI-6-2021" "PHOEBE-2020" "SAT368" "SAT393" "SAT427" "SAT428" "SAT441" "SAT450" "NOE-7-2013" "SAI-7-2021" "URA111" "URA112" "URA115" "URA116" "SAI-8-2015" "SAI-8-2021" "NEP086" "NEP095" "ASTMOONS-2025"

Planetary and satellites theories used for the computations (details)

places
string (places) unique
Default: "astrometric"
Enum: "geometric" "astrometric" "apparent"

Applied corrections to compute the positions of the celestial bodies and the observer.

  • geometric : The position of the observed body and the position of the observer are computed at the same date of the observation. No light-time correction is applied.
  • astrometric : The position of the observer is computed at the date of the observation and the position of the observed body is computed at the different time using the light-time correction.
  • apparent : The apparent place of the observed body represents the position of the celestial body as it would be seen for the observer at the requested dates. The positions of the observer and the observed body are computed using the following corrections : light-time, relativistic light-deflection, aberrations of light. The atmosphere of the observer is assumed to be transparent and non-refracting.
format
string (format) unique
Default: "json"
Enum: "json" "text"

Specified output format

coord-format
string (coord-format)
Default: "dec"
Enum: "dec" "sexa"

Coordinates (angles, ...) of the response are expressed in decimal or in sexagesimal.

  • dec : decimal angles
  • sexa : sexagesimal angles.
distance-unit
string (distance-unit) unique
Default: "Km"
Enum: "Km" "AU"

Distance unit expressed in Km or in AU.

quantities
Array of strings (quantities) non-empty unique
Default: ["cart"]
Items Enum: "cart" "radec" "lonlat" "lhadec" "azel" "dist" "tancart" "tanaz" "deltaradec" "el" "pan" "par" "sspa" "sopc" "sopg" "sopd" "sspc" "sspg" "sspd" "am" "angdiam" "il" "mag" "phase" "Ls" "lt" "era" "eqe" "eqo" "eqt" "lst" "TT-TDB" "TT-UT1"

Computed quantities of the observed body.

  • am : Relative air mass, ratio of absolute air masses at direction target relative to that at zenith. That quantity is stored in airMass.
  • angdiam : Apparent equatorial angular diameter of the body, as if the body were visible to the observer and fully illuminated by the Sun. That quantity is stored in angDiameter.
  • cart : absolute cartesian coordinates, expressed in frame. These coordinates are stored in cartX, cartY and cartZ.
  • radec : absolute equatorial coordinates (right ascension and declination), expressed in frame. These coordinates are stored in RA and DEC.
  • lonlat : absolute ecliptic coordinates (longitude and latitude), expressed in frame. These coordinates are stored in longitude and latitude.
  • hadec : absolute local hour angle and declination coordinates, expressed in the equatorial frame of the observer. These coordinates are stored in HA and DEC.
  • azel : local coordinates (azimuth and elevation), expressed in the local tangent frame to the ellipsoid. The azimuth is computed from the North. These coordinates are stored in azimuth and elevation.
  • dist : distance between the observed body and the observer. That coordinate is stored in distance.
  • tancart : tangent cartesian coordinates to the celestial sphere, relative to the reference. The Y-axis is in the direction to the 'north' pole of the frame and the X-axis is in the direction to the East (increasing right ascension). These coordinates are stored in X and Y.
  • tanaz : tangent coordinates (separation and position angle) to the celestial sphere, relative to the reference. The position angle is computed from the Y-axis. These coordinates are stored in S and positionAngle.
  • deltaradec : relative equatorial coordinates (right ascension and declination) to the reference, expressed in frame. These coordinates are stored in deltaRA and deltaDEC.
  • el : elongation between the observed body and the reference seen by the observer. That coordinate is stored in elongation.
  • il : illuminated fraction of a body. The body is illuminated by the Sun. That quantity is stored in illuminatedFraction.
  • mag : observed apparent visual magnitude. That quantity is stored in magnitude.
  • pan : position angle of the north pole of the body. That quantity is stored in PAn.
  • par : parallactic angle of the body. That quantity is stored in parallactic.
  • phase : observed phase of the body, illuminated by the Sun. That quantity is stored in phase.
  • sopc : Planetocentric coordinates (longitude and latitude) of the sub-observer point, expressed in the frame of the observed body (XY plane is the equator of the observed body, origin of longitudes is its first meridian). These coordinates are stored in sopcLongitude and sopcLatitude.
  • sopg : Planetographic coordinates (longitude and latitude) of the sub-observer point, expressed in the frame of the observed body (XY plane is the equator of the observed body, origin of longitudes is its first meridian, the direction of the longitudes depends on the body). These coordinates are stored in sopgLongitude and sopgLatitude.
  • sopd : Planetodetic coordinates (longitude and latitude) of the sub-observer point, expressed in the frame of the observed body (XY plane is the equator of the observed body, origin of longitudes is its first meridian). These coordinates are stored in sopdLongitude and sopdLatitude.
  • sspa : Position angle of the subsolar point of the body from the Celestial North. That coordinate is stored in sspa.
  • sspc : Planetocentric coordinates (longitude and latitude) of the sub-solar point, expressed in the frame of the observed body (XY plane is the equator of the observed body, origin of longitudes is its first meridian). These coordinates are stored in sopcLongitude and sopcLatitude.
  • sspg : Planetographic coordinates (longitude and latitude) of the sub-solar point, expressed in the frame of the observed body (XY plane is the equator of the observed body, origin of longitudes is its first meridian, the direction of the longitudes depends on the body). These coordinates are stored in sspgLongitude and sspgLatitude.
  • sspd : Planetodetic coordinates (longitude and latitude) of the sub-solar point, expressed in the frame of the observed body (XY plane is the equator of the observed body, origin of longitudes is its first meridian). These coordinates are stored in sspdLongitude and sspdLatitude.
  • Ls : Apparent longitude of the Sun for the body, expressed in the orbital plane of the body and with the origin of the longitude at the equinox direction of the body. Values of Ls of 0°, 90°, 180° and 270° correspond to the northern hemisphere spring equinox, northern summer solstice, northern autumnal equinox, and northern winter solstice for the planet. That coordinate is stored in Ls.
  • lt : light-time from the observed body to the observer. That coordinate is stored in lightTime.
  • era : Earth Rotation Angle. That coordinate is stored in ERA.
  • eqe : Equation of the equinoxes. That coordinate is stored in EQE.
  • eqo : Equation of the origins. That coordinate is stored in EQO.
  • eqt : Equation of Time. That coordinate is stored in EQT.
  • lst : Local sidereal time of the observer. That coordinate is stored in LST.
  • TT-TDB : Difference between the time TT and TDB (=TT-TDB). That coordinate is stored in TT-TDB.
  • TT-UT1 : Difference between the time TT and UT1 (=TT-UT1). That coordinate is stored in TT-UT1.
theme
string (theme) unique
Default: "default"
Enum: "default" "dynastvo"

Specified a preconfigured theme.

extraprecision
integer [ 0 .. 3 ]
Default: 0

Number of additional digits for the distances and angles in the response. The computation are always done using the same precision (double-precision) but the number of digits of the floating-point numbers in the response may be changed using this parameter.

Responses

Request samples

Content type
application/json
Example
{
  • "body": 299,
  • "observer": "obscode:007",
  • "frame": "TrueOfDate",
  • "timescale": "UTC",
  • "reference": "origin",
  • "places": "apparent",
  • "quantities": [
    ],
  • "date-set": [
    ]
}

Response samples

Content type
application/json
{
  • "link": {},
  • "request": {
    },
  • "response": {
    }
}

Sky chart

Get a sky chart at a given date an location. The map includes the Sun, the Moon, the eight planets and the stars brighter than a selected limit.

Examples:

Capabilities : https://opale.imcce.fr/api/v1/chart/sky/capability

query Parameters
required
now (string) or number or string

Date of the sky chart. The timescale of this date is given by the timescale. The calendar of this date is given by the parameter calendar.

required
observatory code (string) or Array of (geodetic latitude, longitude, and optionally the altitude) (numbers)
Default: "obscode:007"
Example: observer=48&observer=150&observer=0

Location of the observer on the Earth. A geocentric position (obscode:500) is not allowed if the parameter map-coordinate-system equals azel.

format
string
Default: "image"
Value: "image"
Example: format=image

The response format. The default response format is given by the header request Accept. If format is given, the header request Accept is ignored. If the format is image, the image bytes are directly streamed to the client.

image-style
string
Default: "ssp"
Enum: "ssp" "sspdark" "newsletter" "astaf"
Example: image-style=ssp

The style of the exported image. The default style of the export image is ssp.

timescale
required
string (timescale) ^(UTC([+-][01][0-9]:[0-5][0-9])?)|(UT1)|([/A-...
Default: "UTC"

All dates and times of the request or response are expressed in this timescale.

The supported timescales are :

  • UTC
  • UTC±hh:mm , where ±hh:mm is the offset is the difference in hours and minutes from UTC.
  • name of a time zone. This name is one of the TZ database name (list) e.g., Europe/Paris.
  • UT1
calendar
string (calendar)
Default: "gregorian"
Enum: "gregorian" "julian" "JD"
Example: calendar=gregorian

All dates and times of the request or response are expressed in this calendar.

The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.
  • JD : Julian date or day. The Julian Date (JD) of any instant is the Julian day number for the preceding noon plus the fraction of the day since that instant. It follows the resolution B1 of the XXIIIrd IAU General Assembly.
image-format
string
Default: "png"
Enum: "png" "svg"
Example: image-format=png

The format of the exported image. The default format of the exported image is png.

Array of integers or strings = 2 items
Default: [1400,1400]
Example: image-size=1400,1400

The size (width , height) of the exported image in pixels. The default size of the export image is (1400,1400). If one component is auto, then its size in pixels is automatically set to maximize the visible world depending of the projection.

image-font-scale
number [ 0.5 .. 4 ]
Default: 1
Example: image-font-scale=1

Font scale factor applied to the labels.

magnitude-limit
number [ 5 .. 8 ]
Default: 5
Example: magnitude-limit=5

Show stars brighter than this magnitude.

map-projection
string
Default: "ESRI:54026"
Enum: "EPSG:9820" "EPSG:9825" "ESRI:54026"
Example: map-projection=ESRI:54026

The projection of the map. The default projection is the stereographic projection (ESRI:54026).

  • EPSG:9820 : Lambert Azimuthal Equal Area
  • EPSG:9825 : Pseudo Plate Carree
  • ESRI:54026 : Stereographic projection
map-center
Array of numbers = 2 items [ items [ -180 .. 180 ] ]
Default: [180,90]
Example: map-center=180,90

The coordinates of the center of the projection of the map, expressed in decimal degrees. The type of these coordinates depends on the parameter map-coordinate-system. The azimuth (right ascension or longitude) is the first argument and the elevation (declination or latitude) is the second argument.

automatic reference point (string) or Array of user-defined reference point (integers)
Default: "auto"
Example: map-reference-point=auto

Reference point for the projection.

map-coordinate-system
string
Default: "azel"
Enum: "azel" "ecli" "equa"
Example: map-coordinate-system=azel

The celestial coordinate system specifing the center of the map. The default celestial coordinate system is the horizontal system (azel).

  • azel : horizontal system; Its fundamental plane is the horizon of the observer. The coordinates are azimuth and elevation.
  • equa : equatorial system; Its fundamental plane is the true equator plane. The coordinates are right ascension and declination.
  • ecli : ecliptic system; Its fundamental plane is the true ecliptic plane. The coordinates are longitude and latitude.
map-zoom
number [ 1 .. 100 ]
Default: 1
Example: map-zoom=1

The zoom level. The lowest level 1 is the lowest zoom level (fully zoomed out) and 100 is the highest level (fully zoomed in). The zoom level determines how much of the world is visible on a map.

map-labels
string
Default: "fr"
Enum: "en" "fr"
Example: map-labels=fr

Display the labels on the map.

  • en : english labels are displayed.
  • fr : french labels are displayed.
map-solarsystembodies-label
boolean
Default: false
Example: map-solarsystembodies-label=false

Show the name of the solar system bodies.

map-ecliptic-plane
boolean
Default: false
Example: map-ecliptic-plane=false

Show the ecliptic plane as a solid line on the map with its name.

map-cardinal-points
boolean
Default: false
Example: map-cardinal-points=false

Show the cardinal points, if the parameter map-coordinate-system equals to azel.

map-observer
Array of strings unique
Default: []
Items Enum: "coord" "name"
Example: map-observer=coord,name

Show the coordinates and/or location name of the observer.

  • coord : coordinates of the observer
  • name : nearest known location name of the observer (a populated place with more than 5000 people). If no populated place is found, no name is displayed.
map-zenith
boolean
Default: false
Example: map-zenith=false

Show the local zenith, if the parameter map-coordinate-system equals to azel.

map-meridian
boolean
Default: false
Example: map-meridian=false

Show the local meridian as a solid line on the map with its name, if the parameter map-coordinate-system equals to azel..

map-time
boolean
Default: false
Example: map-time=false

Show the date, time and timescale of the sky chart.

map-constellation-link
boolean
Default: false
Example: map-constellation-link=false

Display the link of the constellations on the map.

map-constellation-label
boolean
Default: false
Example: map-constellation-label=false

Display the name of the constellations on the map.

map-constellation-boundary
boolean
Default: false
Example: map-constellation-boundary=false

Display the boundaries of the constellations on the map.

map-milkyway
boolean
Default: false
Example: map-milkyway=false

Show the milky way.

Responses

Response samples

Content type
application/json
{
  • "instance": "string",
  • "title": "Parameter in the URI path has an invalid value",
  • "detail": [
    ],
  • "status": 0
}

Occultations

Get all occultations of a solar system body or of a star for an optional given date. If the date is not provided, the occultations of the current year are returned. The instants of the events are given in the timescale UTC for the dates after 1962 and UT1 for the dates before 1962.

A response, which contains the information about the occultations, is returned to the client encoded in json format, by default. A map of the visibility of the occultation on the Earth is streamed to the client if the header Accept of the request specifies the MIME media types image/svg+xml, application/pdf or application/postscript and the date is a calendar day. This behavior can be replaced by the query parameter format. The geojson path or lines are returned only if the global circumstances of a specific occultation is requested.

If the position of the center of a planet is not available for a requested time, as no satellites theory is available at that requested time, then the position of the barycenter of the planetary system is used for the computation of the position of the planet.

Examples:

path Parameters
body
required
string^\d{3,9}|HIP-\d{1,6}$
Example: 499

Occulted body:

  • NAIF identification number of the occulted body
  • identifier of an occulted star : HIP number, WDS identifier . The NAIF identification number should be the center of mass of the planet, and not its barycenter of the planet and satellites.

example:

  • 499 for Mars
  • 599 for Jupiter
  • HIP-49669 for Regulus.
required
Year (string) or Calendar date (string)
Example: 2025

Filter by year or day.

The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.
query Parameters
nbd
integer [ 1 .. 10 ]
Default: 1
Example: nbd=1

Number of years to compute. This parameter is ignored if the parameter is not a year

occulting
string^\d{3,8}$
Default: "301"
Example: occulting=301

NAIF identification number of the occulting body. The NAIF identification number should be the center of mass of the body (Moon, planet, asteroid), and not its barycenter

NAIF Identification (integer) or observatory code (string) or Array of (geodetic latitude, longitude, and optionally the altitude) (numbers)

Location of the observer. General circumstances of the occultations are computed (default case) if the observer is located at the geocenter, otherwise, local circumstances are computed.

format
string
Default: "json"
Enum: "json" "image" "video"
Example: format=json

The response format. The default response format is given by the header request Accept. If format is given, the header request Accept is ignored. If the format is image, the image bytes are directly streamed to the client.

image-format
string
Default: "svg"
Enum: "svg" "eps" "pdf"
Example: image-format=svg

The format of the exported image. The default format of the exported image is svg.

video-format
string
Default: "mp4"
Enum: "hls" "mp4" "webm"
Example: video-format=mp4

The format of the exported video. The default format of the exported video is mp4.

video-definition
string
Default: "HD"
Enum: "custom" "SD" "HD" "FHD"
Example: video-definition=HD

The definition of the exported video. The default definition of the exported video is HD.

  • custom : the resolution is given by the parameter image-size.
  • SD : the number of lines of video is set to 576. The width of the video is adjusted in order to respect the projection.
  • HD : the number of lines of video is set to 720. The width of the video is adjusted in order to respect the projection.
  • FHD : the number of lines of video is set to 1080. The width of the video is adjusted in order to respect the projection.
Array of integers or strings = 2 items
Default: [800,600]
Example: image-size=800,600

The size (width , height) of the exported image in pixels. The default size of the export image is (800,600). If one component is auto, then its size in pixels is automatically set to maximize the visible world depending of the projection.

image-style
string
Default: "ssp"
Enum: "ssp" "newsletter"
Example: image-style=ssp

The style of the exported image. The default style of the export image is ssp.

map-projection
string
Default: "EPSG:3395"
Enum: "EPSG:3395" "EPSG:3857" "EPSG:9840" "EPSG:9820" "EPSG:9825" "ESRI:54026"
Example: map-projection=EPSG:3395

The projection of the map. The default projection is the Mercator conformal projection (EPSG:3395).

  • EPSG:3395 : Mercator conformal projection
  • EPSG:3857 : Web-Mercator or pseudo-Mercator projection
  • EPSG:9820 : Lambert Azimuthal Equal Area
  • EPSG:9825 : Pseudo Plate Carree
  • EPSG:9840 : Orthographic projection
  • ESRI:54026 : Stereographic projection
map-center
Array of numbers = 2 items [ items [ -180 .. 180 ] ]
Default: [0,0]
Example: map-center=0,0

The geodetic longitude and latitude of the center of the projection of the map, expressed in decimal degrees. The longitude is the first argument and the latitude is the second argument.

map-theme
string
Default: "land-small"
Enum: "land-small" "land-medium" "country-small" "country-medium"
Example: map-theme=land-small

The background theme of the map. The default content include the lands and major islands. Images produced with the theme '-small' have a size in bytes smaller than those generated with '-medium'.

  • land-small : show the lands and major islands. Suitable for schematic map of the occultation
  • land-medium : show the lands and major islands. Suitable for detailed map of the occultation
  • country-small : show the country boundaries. Suitable for schematic map of the occultation
  • country-medium : show the country boundaries. Suitable for detailed map of the occultation
map-zoom
number [ 1 .. 20 ]
Default: 1
Example: map-zoom=1

The zoom level. The lowest level 1 is the lowest zoom level (fully zoomed out) and 20 is the highest level (fully zoomed in). The zoom level determines how much of the world is visible on a map.

map-labels
string
Default: "none"
Enum: "none" "en" "fr"
Example: map-labels=none

Display the label of the lines of the events on the map.

  • none : no label is displayed.
  • en : english labels (P1, U1, U2, U3, U4, P4) are displayed.
  • fr : french labels (P1, O1, T1, T2, O2, P2) are displayed.

Responses

Response samples

Content type
{
  • "link": {},
  • "request": {
    },
  • "response": {
    }
}

Extreme elongations

Get all minimal elongations or greastest elongations between two bodies over a given timespan. The elongation is the angle, or angular distance, between the astrometric direction of the body and reference from the observer. The position of the observer is computed at the date of the observation and the position of the observed bodies are computed at the different time using the light-time correction. No relativistic light-deflection or refraction correction is applied. The atmosphere of the observer is assumed to be transparent and non-refracting. The instants of the events are given in the timescale UTC by default.

A response, which contains the information about all phenomena, is returned to the client encoded in json format.

Examples:

query Parameters
body
required
string^\d{1,9}|HIP-\d{1,6}$
Default: "1"
Example: body=1

Observed body:

  • NAIF identification number of the observed body (list)
  • identifier of an observed star : HIP number, WDS identifier.

example:

  • 4 for Mars
  • HIP-49669 for Regulus.
reference
required
integer
Default: 10
Example: reference=10

NAIF identification number of the reference point (list)

required
observatory code (string) or Array of (geodetic latitude, longitude, and optionally the altitude) (numbers) or NAIF Identification (integer)

Location of the observer.

required
number or string

Beginning of the timespan. The timescale of this date is given by the timescale. The calendar of this date is given by the parameter calendar.

calendar
string (calendar)
Default: "gregorian"
Enum: "gregorian" "julian" "JD"
Example: calendar=gregorian

All dates and times of the request or response are expressed in this calendar.

The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.
  • JD : Julian date or day. The Julian Date (JD) of any instant is the Julian day number for the preceding noon plus the fraction of the day since that instant. It follows the resolution B1 of the XXIIIrd IAU General Assembly.
nbd
integer [ 14 .. 36525 ]
Default: 365
Example: nbd=365

Length of the timespan, expressed in days

coord-format
string (coord-format)
Default: "dec"
Enum: "dec" "sexa"
Example: coord-format=dec

Coordinates (angles, ...) of the response are expressed in decimal or in sexagesimal.

  • dec : decimal angles
  • sexa : sexagesimal angles.
extrema
required
string
Default: "min"
Enum: "min" "max"
Example: extrema=min

Minimum or maximum elongations

timescale
string (timescale) unique
Default: "UTC"
Enum: "TT" "UTC" "UT1"
Example: timescale=UTC

All dates and times of the request or response are expressed in this timescale.

Before the January 1st 1961 0h UTC, the difference between the timescale UTC and TAI is constant and equals to 0. For all dates expressed in UTC after the last leap second, the difference between the timescale UTC and TAI is constant.

The timescale UT1 is computed using the EOP series C04 when they are available. Before and after the EOP series, UT1 is adjusted using splines and parabola to the available observations.

Responses

Response samples

Content type
application/json
{
  • "link": {},
  • "request": {
    },
  • "response": {
    }
}

Extreme distances

Get all minimum and maximum geometric distances between two bodies over a given timespan. No light-time, aberration or refraction correction is applied. The instants of the events are given in the timescale UTC by default.

A response, which contains the information about all phenomena, is returned to the client encoded in json format.

Examples:

query Parameters
required
observatory code (string) or Array of (geodetic latitude, longitude, and optionally the altitude) (numbers) or NAIF Identification (integer)

NAIF identification number of the two bodies list

required
number or string

Beginning of the timespan. The timescale of this date is given by the timescale. The calendar of this date is given by the parameter calendar.

calendar
required
string (calendar)
Default: "gregorian"
Enum: "gregorian" "julian" "JD"
Example: calendar=gregorian

All dates and times of the request or response are expressed in this calendar.

The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.
  • JD : Julian date or day. The Julian Date (JD) of any instant is the Julian day number for the preceding noon plus the fraction of the day since that instant. It follows the resolution B1 of the XXIIIrd IAU General Assembly.
nbd
integer [ 14 .. 36525 ]
Default: 365
Example: nbd=365

Length of the timespan, expressed in days

distance-unit
string (distance-unit) unique
Default: "Km"
Enum: "Km" "AU"
Example: distance-unit=Km

Distances of the response are expressed in Km or in AU.

timescale
string (timescale) unique
Default: "UTC"
Enum: "TT" "UTC" "UT1"
Example: timescale=UTC

All dates and times of the request or response are expressed in this timescale.

Before the January 1st 1961 0h UTC, the difference between the timescale UTC and TAI is constant and equals to 0. For all dates expressed in UTC after the last leap second, the difference between the timescale UTC and TAI is constant.

The timescale UT1 is computed using the EOP series C04 when they are available. Before and after the EOP series, UT1 is adjusted using splines and parabola to the available observations.

Responses

Response samples

Content type
application/json
{
  • "link": {},
  • "request": {
    },
  • "response": {
    }
}

Oppositions

Get all oppositions of a body for a geocentric observer relative to the Sun over a given timespan in the mean ecliptic of the date. Light-time and aberration corrections are applied. The instants of the events are given in the timescale UTC by default.

A response, which contains the information about all phenomena, is returned to the client encoded in json format.

Examples:

path Parameters
body
required
integer >= 4
Example: 5

NAIF identification number of the body (list)

query Parameters
required
number or string

Beginning of the timespan. The timescale of this date is given by the timescale. The calendar of this date is given by the parameter calendar.

timescale
required
string (timescale) ^(UTC([\+-][01][0-9]:[0-5][0-9])?)|(UT1)$
Default: "UTC"

All dates and times of the request or response are expressed in this timescale.

The supported timescales are

  • UTC
  • UTC±hh:mm , where ±hh:mm is the difference in hours and minutes from UTC. The plus sign math symbol, in the character ±, must be encoded using the characters %2B.
  • UT1

Before the January 1st 1961 0h UTC, the difference between the timescale UTC and TAI is constant and equals to 0. For all dates expressed in UTC after the last leap second, the difference between the timescale UTC and TAI is constant.

The timescale UT1 is computed using the EOP series C04 when they are available. Before and after the EOP series, UT1 is adjusted using splines and parabola to the available observations.

calendar
required
string (calendar)
Default: "gregorian"
Enum: "gregorian" "julian"
Example: calendar=gregorian

All dates and times of the request or response are expressed in this calendar.

The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.
nbd
required
integer [ 1 .. 36525 ]
Default: 3652
Example: nbd=3652

The number of days to compute

Responses

Response samples

Content type
application/json
{}

Upcoming occultations

Get the upcoming occultations. The following upcoming occultations are computed :

  • Planets occulted by the Moon.
  • Stars, brigther than the visual apparent magnitude 3, occulted by the Moon

Examples: https://opale.imcce.fr/api/v1/upcoming/occultations

Responses

Response samples

Content type
application/json
{}

Residuals

Compute the residuals (O-C) of the positions for a body at a given location. The set of dates and the observations (spherical coordiantes) are provided in the body request and expressed in the timescale specified by the parameter timescale.

A response, which contains the information about the requested redisuals, is returned to the client encoded in json format. The residual are always expressed in arcseconds.

Request Body schema: application/json
body
required
integer >= 1

NAIF identification number of the observed body (list)

required
observatory code (string) or Array of (geodetic latitude, longitude, and optionally the altitude) (numbers) or NAIF Identification (integer)

Location of the observer.

Types of observers :

  • case of observer's location is at an Observatory, given by its IAU/MPC observatory code (list). Example : "observer": "obscode:007"

  • case of observer's location is at the center of the celestial body given by its NAIF identification number (list)
    Example : "observer": 599

  • case of terrestrial observer's location given by a GeoJson point (geodetic coordinates). Coordinates of the point on the Earth (longitude, latitude and optionally the altitude). Example : "observer": [48.8534,2.3488,39]

required
Array of numbers or Calendar date (string) [ 1 .. 10000 ] items

Set of dates of the result. This date is expressed using the standard ISO8601: YYYY-MM-DDTHH:MM:SS.SSS or using Julian Day format . The timescale of this date is given by the timescale.

frame
string (frame) unique
Default: "BCRF"
Enum: "BCRF" "GCRF" "TrueOfDate" "MeanJ2000" "EclipticJ2000" "EclipticTrueOfDate" "BodyFixed" "GTRF" "LocalCelestiodeticENU"

Reference frame. The coordinates are expressed in this frame.

  • BCRF : Barycentric Celestial Reference Frame; origin is the Solar System Barycenter, axes are aligned with International Celestial Reference Frame.
  • GCRF : Geocentric Celestial Reference Frame; origin is the Earth's center of mass, axes are aligned with International Celestial Reference Frame.
  • TrueOfDate : XY plane is the true equator of date, origin of longitudes is the equinox of date
  • MeanJ2000 : Mean Equinox/Mean Equator J2000; XY plane is the mean equator J2000.
  • EclipticJ2000 : Mean Equinox/Mean Ecliptic J2000; XY plane is the mean ecliptic J2000.
  • EclipticTrueOfDate : XY plane is the ecliptic of date, origin of longitudes is true equinox of date.
  • BodyFixed : XY plane is the equator of the body, origin of longitudes is the first meridian ; origin is the center of mass of the body. The surface of the body is fixed in this frame. This frame rotates with the associated body.
  • GTRF : the Geocentric Terrestrial Reference Frame, same as BodyFixed for the Earth.
  • LocalCelestiodeticENU : Frame associated to a position near the surface of a body ; The origin of the frame is at the defining celestiodetic point location. Z axis towards Zenith direction is normal to the ellipsoid. XY axis in the local horizontal plane (normal to zenith direction). Y axis is following the local meridian towards North.
timescale
string (timescale) unique
Default: "UTC"
Enum: "TT" "UTC" "UT1"

All dates and times of the request or response are expressed in this timescale.

Before the January 1st 1961 0h UTC, the difference between the timescale UTC and TAI is constant and equals to 0. For all dates expressed in UTC after the last leap second, the difference between the timescale UTC and TAI is constant.

The timescale UT1 is computed using the EOP series C04 when they are available. Before and after the EOP series, UT1 is adjusted using splines and parabola to the available observations.

calendar
string (calendar)
Default: "gregorian"
Enum: "gregorian" "julian" "JD"

All dates and times of the request or response are expressed in this calendar.

The supported calendars are :

  • gregorian : Gregorian calendar. In early eras, the adopted calendar is the proleptic Gregorian calendar. It complies with the ISO 8601 standard.
  • julian : Julian calendar. In early eras, the adopted calendar is the proleptic Julian calendar. It follows the astronomical year numbering, which includes the year 0.
  • JD : Julian date or day. The Julian Date (JD) of any instant is the Julian day number for the preceding noon plus the fraction of the day since that instant. It follows the resolution B1 of the XXIIIrd IAU General Assembly.
observations
required
Array of strings [ 1 .. 10000 ] items [ items ]

Array of the observed spherical coordinates. Each element of the array is an array of 2 strings. Theses strings may be expressed as decimal or sexagesimal numbers depending on the value of coord

coord
required
string
Enum: "RA/DEC-dec" "RA/DEC-sexa"

Type of the observations :

  • RA/DEC-dec : right ascension and declination as decimal numbers. The right ascension is expressed in decimal hours [0,24[ and the declination is expressed in decimal degrees between [-90, 90].
  • RA/DEC-sexa : right ascension and declination as sexagesimal numbers. The right ascension is expressed in sexagesimal hours [ "00 00 00","24 00 00"[ and the declination is expressed in sexagesimal degree between [ "-90 00 00","90 00 00"]. The component of the sexagesimal entries are separated by spaces
theory
Array of strings (theory) non-empty unique
Default: ["INPOP19A","NOE-4-2020","NOE-5-2021","SAI-5-2021","NOE-6-2018","SAI-6-2021","PHOEBE-2020","NOE-7-2013","SAI-7-2021","SAI-8-2015","SAI-8-2021","ASTMOONS-2025"]
Items Enum: "DE441" "INPOP19A" "NOE-4-2020" "MAR097" "NOE-5-2021" "SAI-5-2021" "JUP365" "JUP344" "NOE-6-2018" "SAI-6-2021" "PHOEBE-2020" "SAT368" "SAT393" "SAT427" "SAT428" "SAT441" "SAT450" "NOE-7-2013" "SAI-7-2021" "URA111" "URA112" "URA115" "URA116" "SAI-8-2015" "SAI-8-2021" "NEP086" "NEP095" "ASTMOONS-2025"

Planetary and satellites theories used for the computations (details)

Responses

Request samples

Content type
application/json
{
  • "body": 5,
  • "calendar": "gregorian",
  • "date-set": [
    ],
  • "observer": 399,
  • "timescale": "UTC",
  • "observations": [
    ],
  • "theory": [
    ],
  • "coord": "RA/DEC-dec"
}

Response samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}