{ "openapi": "3.0.2", "info": { "title": "OPALE API", "description": "OPALE provides a catalog of APIs to fetch the ephemerids data", "version": "20250228.0", "termsOfService": "https://opale.imcce.fr/terms/", "contact": { "name": "OPALE API", "url": "https://opale.imcce.fr/", "email": "no-reply@imcce.fr" }, "license": { "name": "", "url": "https://opale.imcce.fr/terms/" } }, "servers": [ { "url": "https://opale.imcce.fr/api", "variables": {}, "description": "production server" } ], "components": { "schemas": { "observer_terrestrial_longitude_latitude_altitude": { "description": "Location of the observer on the Earth given its geodetic coordinates.", "type": "array", "title": "(geodetic latitude, longitude, and optionally the altitude)", "items": { "description": "Coordinates of the observer on the Earth : geodetic latitude, longitude, and optionally the altitude.\n\nThe geodetic latitude and longitude are expressed in decimal degree in the datum WGS84.\nSouth latitude has a negative sign.\nWest longitude has a negative sign.\n\nThe altitude is expressed in meters over the WGS84 ellipsoid.", "type": "number", "minimum": -10000, "maximum": 10000, "example": [ 0, 0 ] }, "minItems": 2, "maxItems": 3, "default": [ 0, 0, 0 ], "example": [ 0, 0 ] }, "observer_terrestrial_observatory_code": { "title": "observatory code", "description": "Location of the observer at an Observatory, given by its IAU/MPC observatory code ([list](https://minorplanetcenter.net/iau/lists/ObsCodesF.html)). The three last characters, after *obscode:*, are the observatory code.", "type": "string", "pattern": "^obscode:[0-9A-Z][0-9A-Z][0-9A-Z]$", "default": "obscode:007", "example": "obscode:007" }, "observer_naif_identification": { "title": "NAIF Identification", "description": "Location of the observer is at the center of the celestial body given by its NAIF identification number ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html))", "type": "integer", "default": 399, "example": 399 }, "observer_geocenter": { "title": "NAIF Identification", "description": "Location of the observer is at the geoenter given by its NAIF identification number ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html))", "type": "integer", "default": 399, "enum": [ 399 ], "example": 399 }, "geojson_point": { "description": "Terrestrial location of the terrestrial observer given by a GeoJson point (geodetic coordinates).", "type": "object", "required": [ "type", "geometry", "properties" ], "properties": { "type": { "description": "Feature of the GeoJson data.", "type": "string", "enum": [ "Feature" ], "default": "Feature", "example": "Feature" }, "geometry": { "description": "Location of the terrestrial observer given by a GeoJson point.", "type": "object", "required": [ "type", "coordinates" ], "properties": { "type": { "description": "Type of the geometry. It should be a point.", "type": "string", "enum": [ "Point" ], "default": "Point", "example": "Point" }, "coordinates": { "description": "Coordinates of the point on the Earth (longitude, latitude and optionally the altitude). The geodetic latitude and longitude are expressed in decimal degree in the datum WGS84.\nSouth latitude has a negative sign.\nWest longitude has a negative sign.\nThe altitude is expressed in meters over the WGS84 ellipsoid.", "type": "array", "minItems": 2, "maxItems": 3, "items": { "type": "number" }, "example": [ 48.8589, 2.3469, 100 ] } }, "example": { "type": "Point", "coordinates": [ 48.8589, 2.3469, 100 ] } }, "properties": { "description": "Properties of the GeoJson point.", "type": "object", "required": [ "coordinatesDMS" ], "properties": { "coordinatesDMS": { "description": "Coordinates of the point on the Earth (longitude, latitude and optionally the altitude). The geodetic latitude and longitude are expressed in sexagesimal degree in the datum WGS84.\nThe format of the geodetic longitude is '+DDD:MM:SS.S' and the geodetic latitude is '+DD:MM:SS.S'. South latitude has a negative sign.\nWest longitude has a negative sign.\nThe altitude is expressed in meters over the WGS84 ellipsoid.", "type": "array", "minItems": 2, "maxItems": 3, "items": { "type": "string" }, "example": [ "+103:27:23.1", "+23:06:09.5", "+0.0" ] } }, "example": { "coordinates": [ "+103:27:23.1", "+23:06:09.5", "+0.0" ] } } }, "example": { "type": "Feature", "properties": {}, "geometry": { "type": "Point", "coordinates": [ 48.8589, 2.3469, 100 ] } } }, "dec-angle": { "title": "decimal angle", "type": "number", "description": "angle as a decimal floating-point number" }, "sexa-angle": { "title": "sexagesimal angle", "type": "string", "description": "angle as a sexagesimal number" }, "angle": { "description": "decimal or sexagesimal angle", "oneOf": [ { "title": "decimal angle", "type": "number", "description": "angle as a decimal floating-point number" }, { "title": "sexagesimal angle", "type": "string", "description": "angle as a sexagesimal number" } ] }, "date": { "description": "calendar date or julian day", "oneOf": [ { "title": "Julian day", "type": "number", "description": "Julian day, valid only if the item response 'calendar' has the value 'JD'" }, { "title": "Gregorian calendar date", "type": "string", "description": "Gregorian date or Gregorian proleptic date (ISO-8601 compliant date), valid only if the item response 'calendar' has the value 'Gregorian'" }, { "title": "Julian calendar date", "type": "string", "description": "Julian date or Julian proleptic date, valid only if the item response 'calendar' has the value 'Julian'. This date is not compliant with the ISO-8601 standard" } ] }, "dec-elapsedtime": { "title": "decimal elapsed time", "type": "number", "description": "elapsed time as a decimal floating-point number" }, "sexa-elapsedtime": { "title": "sexagesimal elapsed time", "type": "string", "description": "elapsed time as a sexagesimal number" }, "lunareclipse_contact": { "description": "Contact event of a lunar eclipse", "nullable": true, "type": "object", "required": [ "date", "axis", "p", "zenith", "Moon", "Sun", "UT1-TT" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "axis": { "description": "Apparent geocentric angular distance between the centers of the Moon and the umbral shadow at time of the event", "$ref": "#/components/schemas/angle" }, "p": { "description": "Position angle of contact on the limb of the Moon measured eastwards from celestial north", "$ref": "#/components/schemas/angle" }, "zenith": { "description": "Location on the Earth having the Moon at zenith at time of the event", "$ref": "#/components/schemas/geojson_point" }, "UT1-TT": { "description": "Difference between UT1 and TT at time of the event, expressed in second", "type": "number" }, "Moon": { "description": "Right ascension, declination, horizontal parallax, apparent semi-diameter of the Moon", "type": "object", "required": [ "RA", "DEC", "parallax", "radius" ], "properties": { "RA": { "description": "Apparent right ascension of the Moon at time of the event", "$ref": "#/components/schemas/angle" }, "DEC": { "description": "Apparent declination of the Moon at time of the event", "$ref": "#/components/schemas/angle" }, "parallax": { "description": "Equatorial horizontal parallax of the Moon at time of the event", "$ref": "#/components/schemas/angle" }, "radius": { "description": "Apparent angular radius of the Moon at time of the event", "$ref": "#/components/schemas/angle" } } }, "Sun": { "description": "Right ascension, declination, horizontal parallax, apparent semi-diameter of the Sun", "type": "object", "required": [ "RA", "DEC", "parallax", "radius" ], "properties": { "RA": { "description": "Apparent right ascension of the Sun at time of the event", "$ref": "#/components/schemas/angle" }, "DEC": { "description": "Apparent declination of the Sun at time of the event", "$ref": "#/components/schemas/angle" }, "parallax": { "description": "Equatorial horizontal parallax of the Sun", "$ref": "#/components/schemas/angle" }, "radius": { "description": "Apparent angular radius of the Sun", "$ref": "#/components/schemas/angle" } } } } }, "solareclipse_contact": { "description": "Contact event of a solar eclipse", "nullable": true, "type": "object", "required": [ "date", "p", "zenith", "location", "Moon", "Sun", "UT1-TT" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "axis": { "description": "Apparent geocentric angular distance between the centers of the Moon and the umbral shadow at time of the event", "$ref": "#/components/schemas/angle" }, "p": { "description": "Position angle of contact on the limb of the Moon measured eastwards from celestial north", "$ref": "#/components/schemas/angle" }, "zenith": { "description": "Position angle of contact on the limb of the Moon measured eastwards from the zenith", "$ref": "#/components/schemas/angle" }, "location": { "description": "Location on the Earth observing this event", "$ref": "#/components/schemas/geojson_point", "nullable": true }, "UT1-TT": { "description": "Difference between UT1 and TT at time of the event, expressed in second", "type": "number" }, "Moon": { "description": "Right ascension, declination, azimuth, elevation, horizontal parallax, apparent semi-diameter, center of figure of the Moon", "type": "object", "required": [ "RA", "DEC", "azimuth", "elevation", "parallax", "radius" ], "properties": { "RA": { "description": "Apparent right ascension of the Moon at time of the event", "$ref": "#/components/schemas/angle" }, "DEC": { "description": "Apparent declination of the Moon at time of the event", "$ref": "#/components/schemas/angle" }, "azimuth": { "description": "Azimuth from the North of the Moon of the body at time of the event", "$ref": "#/components/schemas/angle" }, "elevation": { "description": "Elevation above the horizon of the Moon at time of the event (without refraction)", "$ref": "#/components/schemas/angle" }, "parallax": { "description": "Equatorial horizontal parallax of the Moon at time of the event", "$ref": "#/components/schemas/angle" }, "radius": { "description": "Apparent angular radius of the Moon at time of the event", "$ref": "#/components/schemas/angle" }, "centerOfFigure": { "description": "Offset vector 'center of Mass' to 'center of Figure' of the Moon", "type": "object", "required": [ "deltaRA", "deltaDEC" ], "properties": { "deltaRA": { "description": "Offset in apparent right ascension of the vector 'center of Mass' to 'center of Figure' of the Moon at time of the event", "$ref": "#/components/schemas/angle" }, "deltaDEC": { "description": "Offset in apparent declination of the vector 'center of Mass' to 'center of Figure' of the Moon at time of the event", "$ref": "#/components/schemas/angle" } } } } }, "Sun": { "description": "Right ascension, declination, azimuth, elevation, horizontal parallax, apparent semi-diameter of the Sun", "type": "object", "required": [ "RA", "DEC", "azimuth", "elevation", "parallax", "radius" ], "properties": { "RA": { "description": "Apparent right ascension of the Sun at time of the event", "$ref": "#/components/schemas/angle" }, "DEC": { "description": "Apparent declination of the Sun at time of the event", "$ref": "#/components/schemas/angle" }, "azimuth": { "description": "Azimuth from the North of the Sun at time of the event", "$ref": "#/components/schemas/angle" }, "elevation": { "description": "Elevation above the horizon of the Sun at time of the event (without refraction)", "$ref": "#/components/schemas/angle" }, "parallax": { "description": "Equatorial horizontal parallax of the Sun", "$ref": "#/components/schemas/angle" }, "radius": { "description": "Apparent angular radius of the Sun", "$ref": "#/components/schemas/angle" } } } } }, "occultation_contact": { "description": "Contact event of an occultation", "nullable": true, "type": "object", "required": [ "date", "p", "zenith", "location", "occultingBody", "Sun", "occultedBody", "UT1-TT", "bodiesElongation" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "p": { "description": "Position angle of contact on the limb of the occulting body measured eastwards from celestial north", "$ref": "#/components/schemas/angle" }, "zenith": { "description": "Position angle of contact on the limb of the occulting body measured eastwards from the zenith", "$ref": "#/components/schemas/angle" }, "bodiesElongation": { "description": "Minimal elongation between the occulting and occulted and the body", "$ref": "#/components/schemas/angle" }, "location": { "description": "Location on the Earth observing this event", "$ref": "#/components/schemas/geojson_point", "nullable": true }, "UT1-TT": { "description": "Difference between UT1 and TT at time of the event, expressed in second", "type": "number" }, "cuspAngle": { "description": "Cusp angle", "nullable": true, "type": "object", "required": [ "pole", "angle" ], "properties": { "pole": { "description": "Pole of cusp angle", "type": "string", "enum": [ "N", "S" ] }, "angle": { "description": "Signed angle of cusp angle", "$ref": "#/components/schemas/angle" } } }, "occultingBody": { "description": "Right ascension, declination, azimuth, defect illumination, elevation, illuminated fraction, magnitude, horizontal parallax, apparent semi-diameter of the occulting body", "type": "object", "required": [ "RA", "DEC", "azimuth", "illuminatedFraction", "defectIlluminationPositionAngle", "elevation", "magnitude", "parallax", "radius", "solarElongation" ], "properties": { "RA": { "description": "Apparent right ascension of the occulting body at time of the event", "$ref": "#/components/schemas/angle" }, "DEC": { "description": "Apparent declination of the occulting body at time of the event", "$ref": "#/components/schemas/angle" }, "azimuth": { "description": "Azimuth from the North of the occulting body at time of the event", "$ref": "#/components/schemas/angle" }, "illuminatedFraction": { "description": "Illuminated fraction of the occulting body by the Sun", "type": "number" }, "defectIlluminationPositionAngle": { "description": "position angle of the defect illumination by the Sun of the body", "$ref": "#/components/schemas/angle" }, "elevation": { "description": "Elevation above the horizon of the occulting body at time of the event (without refraction)", "$ref": "#/components/schemas/angle" }, "magnitude": { "description": "Magnitude of the occulting body", "type": "number", "nullable": true }, "parallax": { "description": "Equatorial horizontal parallax of the occulting body at time of the event", "$ref": "#/components/schemas/angle" }, "radius": { "description": "Apparent angular radius of the occulting body at time of the event", "$ref": "#/components/schemas/angle" }, "solarElongation": { "description": "Elongation between the Sun and the occulting body at time of the event", "$ref": "#/components/schemas/angle" }, "centerOfFigure": { "description": "Offset vector 'center of Mass' to 'center of Figure' of the occulting body", "type": "object", "required": [ "deltaRA", "deltaDEC" ], "properties": { "deltaRA": { "description": "Offset in apparent right ascension of the vector 'center of Mass' to 'center of Figure' of the occulting body at time of the event", "$ref": "#/components/schemas/angle" }, "deltaDEC": { "description": "Offset in apparent declination of the vector 'center of Mass' to 'center of Figure' of the occulting body at time of the event", "$ref": "#/components/schemas/angle" } } } } }, "Sun": { "description": "Right ascension, declination, azimuth, elevation, illuminated fraction, magnitude, horizontal parallax, apparent semi-diameter of the Sun", "type": "object", "required": [ "RA", "DEC", "azimuth", "elevation", "magnitude", "parallax", "radius" ], "properties": { "RA": { "description": "Apparent right ascension of the Sun at time of the event", "$ref": "#/components/schemas/angle" }, "DEC": { "description": "Apparent declination of the Sun at time of the event", "$ref": "#/components/schemas/angle" }, "azimuth": { "description": "Azimuth from the North of the Sun at time of the event", "$ref": "#/components/schemas/angle" }, "elevation": { "description": "Elevation above the horizon of the Sun at time of the event (without refraction)", "$ref": "#/components/schemas/angle" }, "magnitude": { "description": "Magnitude of the occulting body", "type": "number", "nullable": true }, "parallax": { "description": "Equatorial horizontal parallax of the Sun", "$ref": "#/components/schemas/angle" }, "radius": { "description": "Apparent angular radius of the Sun", "$ref": "#/components/schemas/angle" } } }, "occultedBody": { "description": "Right ascension, declination, azimuth, elevation, illuminated fraction, magnitude, horizontal parallax, apparent semi-diameter of the occulted body", "type": "object", "required": [ "RA", "DEC", "azimuth", "solarElongation", "illuminatedFraction", "defectIlluminationPositionAngle", "elevation", "magnitude", "parallax", "radius" ], "properties": { "RA": { "description": "Apparent right ascension of the occulted body at time of the event", "$ref": "#/components/schemas/angle" }, "DEC": { "description": "Apparent declination of the occulted body at time of the event", "$ref": "#/components/schemas/angle" }, "azimuth": { "description": "Azimuth from the North of the occulted body at time of the event", "$ref": "#/components/schemas/angle" }, "defectIlluminationPositionAngle": { "description": "position angle of the defect illumination by the Sun of the occulted body", "$ref": "#/components/schemas/angle" }, "elevation": { "description": "Elevation above the horizon of the occulted body at time of the event (without refraction)", "$ref": "#/components/schemas/angle" }, "illuminatedFraction": { "description": "Illuminated fraction of the occulted body by the Sun", "type": "number" }, "magnitude": { "description": "Magnitude of the occulting body", "type": "number", "nullable": true }, "parallax": { "description": "Equatorial horizontal parallax of the occulted body", "$ref": "#/components/schemas/angle" }, "radius": { "description": "Apparent angular radius of the occulted body", "$ref": "#/components/schemas/angle" }, "solarElongation": { "description": "Elongation between the Sun and the occulted body at time of the event", "$ref": "#/components/schemas/angle" } } } } }, "step_string": { "description": "Step of time between each computed data", "type": "string", "pattern": "^[0-9]+(\\.[0-9]{0,2})?[DHMS]$", "default": "1D" }, "frame": { "description": "Reference frame. The coordinates are expressed in this frame.\n\n - BCRF : Barycentric Celestial Reference Frame; origin is the Solar System Barycenter, axes are aligned with International Celestial Reference Frame.\n - GCRF : Geocentric Celestial Reference Frame; origin is the Earth's center of mass, axes are aligned with International Celestial Reference Frame.\n - TrueOfDate : XY plane is the true equator of date, origin of longitudes is the equinox of date\n - MeanJ2000 : Mean Equinox/Mean Equator J2000; XY plane is the mean equator J2000.\n - EclipticJ2000 : Mean Equinox/Mean Ecliptic J2000; XY plane is the mean ecliptic J2000.\n - EclipticTrueOfDate : XY plane is the ecliptic of date, origin of longitudes is true equinox of date.\n - 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.\n - GTRF : the Geocentric Terrestrial Reference Frame, same as *BodyFixed* for the Earth.\n - 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.", "type": "string", "default": "BCRF", "uniqueItems": true, "example": "BCRF", "enum": [ "BCRF", "GCRF", "TrueOfDate", "MeanJ2000", "EclipticJ2000", "EclipticTrueOfDate", "BodyFixed", "GTRF", "LocalCelestiodeticENU" ] }, "calendarJulianOrGregorian": { "title": "calendar", "description": "All dates and times of the request or response are expressed in this calendar.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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.", "type": "string", "enum": [ "gregorian", "julian" ], "example": "gregorian", "default": "gregorian" }, "calendar": { "title": "calendar", "description": "All dates and times of the request or response are expressed in this calendar.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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.\n- 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.", "type": "string", "enum": [ "gregorian", "julian", "JD" ], "example": "gregorian", "default": "gregorian" }, "timescaleUTCUT1": { "title": "timescale", "description": "All dates and times of the request or response are expressed in this timescale.\n\nThe supported timescales are :\n\n - UTC\n - UTC\u00b1hh:mm , where \u00b1hh:mm is the offset is the difference in hours and minutes from UTC.\n\nBefore 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.\n\nThe 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.", "type": "string", "pattern": "^(UTC([\\+-][01][0-9]:[0-5][0-9])?)|(UT1)$", "default": "UTC" }, "timescaleUTC": { "title": "timescale", "description": "All dates and times of the request or response are expressed in this timescale.\n\nThe supported timescales are :\n\n - UTC\n - UTC\u00b1hh:mm , where \u00b1hh:mm is the offset is the difference in hours and minutes from UTC.\n - name of a time zone. This name is one of the TZ database name ([list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)) e.g., Europe/Paris.\n - UT1", "type": "string", "pattern": "^(UTC([+-][01][0-9]:[0-5][0-9])?)|(UT1)|([/A-Za-z0-9_+-]{1,30})$", "default": "UTC" }, "theory": { "description": "Planetary and satellites theories used for the computations ([details](theories/))", "type": "array", "items": { "type": "string", "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" ] }, "minItems": 1, "uniqueItems": true, "example": [ "INPOP19A" ], "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" ] }, "reference_naif_identification": { "title": "NAIF identification number", "description": "NAIF identification number of the reference body ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html)). Computed coordinates of the observed body are relative to the position of this body.", "type": "integer", "example": 599 }, "reference_string": { "title": "Reference axis", "description": "Reference axis for the coordinates.\n\n - origin : absolute coordinates are computed in the given *frame*.", "type": "string", "enum": [ "origin" ], "example": "origin", "default": "origin" }, "places": { "description": "Applied corrections to compute the positions of the celestial bodies and the observer.\n\n - 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.\n - 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.\n - 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.", "type": "string", "default": "astrometric", "uniqueItems": true, "enum": [ "geometric", "astrometric", "apparent" ], "example": "astrometric" }, "format": { "description": "Specified output format", "type": "string", "uniqueItems": true, "enum": [ "json", "text" ], "default": "json", "example": "json" }, "coord-format": { "description": "Coordinates (angles, ...) of the response are expressed in decimal or in sexagesimal.\n\n - dec : decimal angles\n - sexa : sexagesimal angles.", "type": "string", "enum": [ "dec", "sexa" ], "default": "dec", "example": "dec" }, "distance-unit": { "description": "Distance unit expressed in Km or in AU.", "type": "string", "enum": [ "Km", "AU" ], "default": "Km", "uniqueItems": true, "example": "Km" }, "quantities": { "description": "Computed quantities of the observed body.\n\n - am : Relative air mass, ratio of absolute air masses at direction target relative to that at zenith. That quantity is stored in *airMass*.\n - 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*.\n - cart : absolute cartesian coordinates, expressed in *frame*. These coordinates are stored in *cartX*, *cartY* and *cartZ*.\n - radec : absolute equatorial coordinates (right ascension and declination), expressed in *frame*. These coordinates are stored in *RA* and *DEC*.\n - lonlat : absolute ecliptic coordinates (longitude and latitude), expressed in *frame*. These coordinates are stored in *longitude* and *latitude*.\n - hadec : absolute local hour angle and declination coordinates, expressed in the equatorial frame of the observer. These coordinates are stored in *HA* and *DEC*.\n - 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*.\n - dist : distance between the observed body and the observer. That coordinate is stored in *distance*.\n - 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*.\n - 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*.\n - deltaradec : relative equatorial coordinates (right ascension and declination) to the *reference*, expressed in *frame*. These coordinates are stored in *deltaRA* and *deltaDEC*.\n - el : elongation between the observed body and the *reference* seen by the observer. That coordinate is stored in *elongation*.\n - il : illuminated fraction of a body. The body is illuminated by the Sun. That quantity is stored in *illuminatedFraction*.\n - mag : observed apparent visual magnitude. That quantity is stored in *magnitude*.\n - pan : position angle of the north pole of the body. That quantity is stored in *PAn*.\n - par : parallactic angle of the body. That quantity is stored in *parallactic*.\n - phase : observed phase of the body, illuminated by the Sun. That quantity is stored in *phase*.\n - 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*.\n - 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*.\n - 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*.\n - sspa : Position angle of the subsolar point of the body from the Celestial North. That coordinate is stored in *sspa*.\n - 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*.\n - 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*.\n - 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*.\n - 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\u00b0, 90\u00b0, 180\u00b0 and 270\u00b0 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*.\n - lt : light-time from the observed body to the observer. That coordinate is stored in *lightTime*.\n - era : Earth Rotation Angle. That coordinate is stored in *ERA*.\n - eqe : Equation of the equinoxes. That coordinate is stored in *EQE*.\n - eqo : Equation of the origins. That coordinate is stored in *EQO*.\n - eqt : Equation of Time. That coordinate is stored in *EQT*.\n - lst : Local sidereal time of the observer. That coordinate is stored in *LST*.\n - TT-TDB : Difference between the time TT and TDB (=TT-TDB). That coordinate is stored in *TT-TDB*.\n - TT-UT1 : Difference between the time TT and UT1 (=TT-UT1). That coordinate is stored in *TT-UT1*.", "type": "array", "items": { "type": "string", "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" ] }, "minItems": 1, "uniqueItems": true, "example": [ "cart", "radec", "dist" ], "default": [ "cart" ] }, "theme": { "description": "Specified a preconfigured theme.", "type": "string", "enum": [ "default", "dynastvo" ], "default": "default", "uniqueItems": true, "example": "dynastvo" }, "timescale": { "description": "All dates and times of the request or response are expressed in this timescale.\n\nBefore 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.\n\nThe 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.", "type": "string", "enum": [ "TT", "UTC", "UT1" ], "default": "UTC", "uniqueItems": true, "example": "UTC" }, "phenomena_satellites_events": { "title": "Event of the phenomena", "description": "Instant, visibility and relative positions of the phenomena", "type": "object", "required": [ "date", "visibility", "S", "positionAngle", "distanceLimb" ], "properties": { "date": { "description": "Instant of the event. This date is expressed using the standard ISO8601: YYYY-MM-DDTHH:MM:SS.SSS . The timescale of this date is given by the *timescale*.", "type": "string", "title": "Iso8601 date", "format": "date-time" }, "deltaCombinedMagnitude": { "description": "Maximum drop of the combined magnitude", "type": "number" }, "visibility": { "description": "Visibility of the phenomena for the observer", "type": "boolean" }, "S": { "description": "Radial distance (sqrt(X^2+Y^2)) in the tangent plane rectangular coordinates of the eclipsed body relative to the eclipsing body, expressed in arcsecond", "type": "number" }, "positionAngle": { "description": "Position angle, clockwise angle measured from the North, This position angle is defined by P=atan2(Y,X) , where X, Y are defined as the tangent plane rectangular coordinates of the eclipsed body relative to the eclipsing body, expressed in degree", "type": "number" }, "distanceLimb": { "description": "Distance of the eclipsed or occulted body to the limb of the planet", "type": "object", "required": [ "radiusPlanet", "angle" ], "properties": { "radiusPlanet": { "description": "Distance of the eclipsed body to the limb of the planet, expressed in radius of the planet", "type": "number" }, "angle": { "description": "Distance of the eclipsed body to the limb of the planet, expressed in arcsecond", "type": "number" } } } } }, "cartX": { "title": "cartX", "description": "Cartesian X Coordinate", "type": "number" }, "cartY": { "title": "cartY", "description": "Cartesian Y Coordinate", "type": "number" }, "cartZ": { "title": "cartZ", "description": "Cartesian Z Coordinate", "type": "number" }, "azimuth": { "title": "azimuth", "description": "Azimuth (azel)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "elevation": { "title": "elevation", "description": "Elevation (azel)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "airMass": { "title": "airMass", "description": "Relative air mass (am)", "type": "number" }, "angDiameter": { "title": "angDiameter", "description": "Angular equatorial diameter", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "illuminatedFraction": { "title": "illuminatedFraction", "description": " Illuminated fraction", "type": "number" }, "magnitude": { "title": "magnitude", "description": "Magnitude", "type": "number" }, "phase": { "title": "phase", "description": "Phase", "type": "number" }, "PAn": { "title": "PAn", "description": "position angle of the north pole", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "parallactic": { "title": "parallactic", "description": "Parallactic angle", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "longitude": { "title": "longitude", "description": "Longitude (lonlat)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "latitude": { "title": "latitude", "description": "Latitude (lonlat)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "RA": { "title": "RA", "description": "Right ascension (radec)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "DEC": { "title": "DEC", "description": "Declination (radec or lhadec)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "ERA": { "title": "ERA", "description": "Earth Rotation Angle (era)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "EQE": { "title": "EQE", "description": "Equation of the equinoxes (eqe)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "EQO": { "title": "EQO", "description": "Equation of the origins (eqo)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "EQT": { "title": "EQT", "description": "Equation of Time (eqt)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "LST": { "title": "LST", "description": "Local apparent sidereal time (lst)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "LHA": { "title": "LHA", "description": "Local hour angle (lhadec)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "distance": { "title": "distance", "description": "Distance between the body and the observer (dist)", "type": "number" }, "elongation": { "title": "elongation", "description": "Elongation (el)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "X": { "title": "X", "description": "X Tangent Cartesian Coordinate", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "Y": { "title": "Y", "description": "Y Tangent Cartesian Coordinate", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "S": { "title": "S", "description": "Separation angle", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "positionAngle": { "title": "positionAngle", "description": "Position angle", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "deltaRA": { "title": "deltaRA", "description": "Difference of right ascension (deltaradec)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "deltaDEC": { "title": "deltaDEC", "description": "Difference of declination (deltaradec)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sspa": { "title": "sspa", "description": "Position angle of the subsolar point from the Celestial North", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sspcLongitude": { "title": "sspcLongitude", "description": "Planetocentric longitude of the subsolar point (ssp)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sspcLatitude": { "title": "sspcLatitude", "description": "Planetocentric latitude of the subsolar point (ssp)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sspgLongitude": { "title": "sspgLongitude", "description": "Planetographic longitude of the subsolar point (ssp)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sspgLatitude": { "title": "sspgLatitude", "description": "Planetographic latitude of the subsolar point (ssp)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sspdLongitude": { "title": "sspdLongitude", "description": "Planetodetic longitude of the subsolar point (ssp)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sspdLatitude": { "title": "sspdLatitude", "description": "Planetodetic latitude of the subsolar point (ssp)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sopcLongitude": { "title": "sopcLongitude", "description": "Planetocentric longitude of the sub-observer point (sop)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sopcLatitude": { "title": "sopcLatitude", "description": "Planetocentric latitude of the sub-observer point (sop)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sopgLongitude": { "title": "sopgLongitude", "description": "Planetographic longitude of the sub-observer point (sop)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sopgLatitude": { "title": "sopgLatitude", "description": "Planetographic latitude of the sub-observer point (sop)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sopdLongitude": { "title": "sopdLongitude", "description": "Planetodetic longitude of the sub-observer point (sop)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "sopdLatitude": { "title": "sopdLatitude", "description": "Planetodetic latitude of the sub-observer point (sop)", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "Ls": { "title": "Ls", "description": "Apparent longitude of the Sun for the body's observer, expressed in the orbital plane of the body and with the origin of the longitude at the equinox direction of the body", "oneOf": [ { "$ref": "#/components/schemas/dec-angle" }, { "$ref": "#/components/schemas/sexa-angle" } ] }, "lightTime": { "title": "lightTime", "description": "light-time (lt)", "oneOf": [ { "$ref": "#/components/schemas/dec-elapsedtime" }, { "$ref": "#/components/schemas/sexa-elapsedtime" } ] }, "TT-TDB": { "title": "TT-TDB", "description": "difference betwen the timescale TT and TDB ( =time_(TT) - time_(TDB) )", "oneOf": [ { "$ref": "#/components/schemas/dec-elapsedtime" }, { "$ref": "#/components/schemas/sexa-elapsedtime" } ] }, "TT-UT1": { "title": "TT-UT1", "description": "difference betwen the timescale TT and UT1 ( =time_(TT) - time_(UT1) )", "oneOf": [ { "$ref": "#/components/schemas/dec-elapsedtime" }, { "$ref": "#/components/schemas/sexa-elapsedtime" } ] } }, "responses": { "416": { "description": "Range Not Satisfiable", "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "description": "identification string of the request", "type": "string" }, "title": { "description": "short description of the error", "example": "Range Not Satisfiable", "type": "string" }, "detail": { "description": "detail information on the error", "type": "string" }, "status": { "description": "HTTP status", "type": "integer" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "description": "identification string of the request", "type": "string" }, "reason": { "description": "short description of the error", "example": "Internal server error", "type": "string" }, "detail": { "description": "detailed information about the error", "type": "string" }, "status": { "description": "HTTP status", "type": "integer" } } } } } }, "400_get": { "description": "Parameters in the URI path does not match the schema API", "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "description": "identification string of the request", "type": "string" }, "title": { "description": "short description of the error", "example": "Parameter in the URI path has an invalid value", "type": "string" }, "detail": { "description": "detailed list of the errors", "type": "array", "items": { "type": "string" } }, "status": { "description": "HTTP status", "type": "integer" } } } } } } } }, "paths": { "/status": { "get": { "summary": "Status of the service", "description": "Get the status of the service.\n\nExample: __URL__/status", "responses": { "200": { "description": "Get the status of the service. The value of status equals to \"OK\" if the service is available\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "description": "free message describing the availability of the service", "type": "string" }, "status": { "type": "string", "enum": [ "OK" ] }, "apiVersion": { "type": "string", "description": "version of the API service" }, "libraryVersion": { "type": "string", "description": "version of the computational library" } }, "example": "EXAMPLESTATUS" } } } } } } }, "/v1/phenomena/eclipses/{body}/{date}": { "get": { "summary": "Eclipses of the Moon or the Sun", "description": "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.\n\nA 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*.\n\nExamples:\n- Get all lunar eclipses on the year 2018 : __URL__/v1/phenomena/eclipses/301/2018\n- Get the data of the lunar eclipse on January 31, 2018 : __URL__/v1/phenomena/eclipses/301/2018-01-31 \n- Get the data of the lunar eclipse on the Julian calendar date January 8, 1582 : __URL__/v1/phenomena/eclipses/301/julian,1582-01-08\n- Get the map of the lunar eclipse on January 31, 2018 in svg image : __URL__/v1/phenomena/eclipses/301/2018-01-31?format=image\n- Get all solar eclipses on the year 1999 : __URL__/v1/phenomena/eclipses/10/1999\n- Get the data of the general circumstances of the solar eclipse on August 11, 1999 : __URL__/v1/phenomena/eclipses/10/1999-08-11\n- Get the data of the local circumstances of the solar eclipse at Metz on August 11, 1999 : __URL__/v1/phenomena/eclipses/10/1999-08-11?observer=49.133333,6.166667\n- Get the map of the solar eclipse on September 01, 2016 in svg image : __URL__/v1/phenomena/eclipses/10/2016-09-01?format=image\n\nCapabilities : __URL__/v1/phenomena/eclipses/capability", "parameters": [ { "in": "path", "name": "body", "description": "NAIF identification number of the body.\n- 10 for solar eclipse\n- 301 for lunar eclipse", "required": true, "schema": { "type": "integer", "enum": [ 10, 301 ], "example": 301 } }, { "in": "path", "name": "date", "description": "Filter by year or day.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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.\n\nIf the calendar is not given, then date is assumed to be expressed in the (proleptic) gregorian calendar.", "required": true, "schema": { "oneOf": [ { "title": "Year", "description": "Year. Only the eclipses occuring this given year are returned.\n\nThe optional calendar specifies the calendar of this year. If the calendar is not given, then the year is assumed to be expressed in the (proleptic) gregorian calendar.", "type": "string", "pattern": "^(gregorian,|julian,)?-?\\d{1,4}$", "example": "2020" }, { "title": "Calendar date", "description": "Calendar date YYYY-MM-DD. Only the eclipse of around this day (previous or next day) is returned.\n\nThe optional calendar specifies the calendar of this date. If the calendar is not given, then date is assumed to be expressed in the (proleptic) gregorian calendar.", "type": "string", "pattern": "^(gregorian,|julian,)?-?\\d{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[12]\\d|3[01])$", "example": "2020-01-10" } ] }, "example": "__CURRENTYEAR__", "style": "simple" }, { "in": "query", "name": "nbd", "description": "Number of years to compute", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "example": 1, "default": 1 } }, { "in": "query", "name": "observer", "description": "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.", "schema": { "oneOf": [ { "$ref": "#/components/schemas/observer_geocenter" }, { "$ref": "#/components/schemas/observer_terrestrial_observatory_code" }, { "$ref": "#/components/schemas/observer_terrestrial_longitude_latitude_altitude" } ] } }, { "in": "query", "name": "format", "description": "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.", "schema": { "type": "string", "enum": [ "json", "image", "video" ], "example": "json", "default": "json" } }, { "in": "query", "name": "image-format", "description": "The format of the exported image. The default format of the exported image is *svg*.", "schema": { "type": "string", "enum": [ "svg", "eps", "pdf" ], "example": "svg", "default": "svg" } }, { "in": "query", "name": "video-format", "description": "The format of the exported video. The default format of the exported video is *mp4*.", "schema": { "type": "string", "enum": [ "hls", "mp4", "webm" ], "example": "mp4", "default": "mp4" } }, { "in": "query", "name": "video-definition", "description": "The definition of the exported video. The default definition of the exported video is *HD*.\n\n - custom : the resolution is given by the parameter *image-size*.\n - SD : the number of lines of video is set to 576. The width of the video is adjusted in order to respect the projection.\n - HD : the number of lines of video is set to 720. The width of the video is adjusted in order to respect the projection.\n - FHD : the number of lines of video is set to 1080. The width of the video is adjusted in order to respect the projection.", "schema": { "type": "string", "enum": [ "custom", "SD", "HD", "FHD" ], "example": "HD", "default": "HD" } }, { "in": "query", "name": "image-size", "description": "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.", "schema": { "type": "array", "items": { "oneOf": [ { "description": "The width or height of the exported image in pixels.", "type": "integer", "minimum": 100, "maximum": 4000, "example": 800, "default": 800 }, { "type": "string", "enum": [ "auto" ], "example": "auto", "default": "auto" } ], "example": [ 800, 600 ] }, "minItems": 2, "maxItems": 2, "default": [ 800, 600 ] } }, { "in": "query", "name": "image-style", "description": "The style of the exported image. The default style of the export image is *ssp*.", "schema": { "type": "string", "enum": [ "ssp", "newsletter" ], "example": "ssp", "default": "ssp" } }, { "in": "query", "name": "map-projection", "description": "The projection of the map. The default projection is the Mercator conformal projection (EPSG:3395).\n - EPSG:3395 : Mercator conformal projection\n - EPSG:3857 : Web-Mercator or pseudo-Mercator projection\n - EPSG:9820 : Lambert Azimuthal Equal Area\n - EPSG:9825 : Pseudo Plate Carree\n - EPSG:9840 : Orthographic projection\n - ESRI:54026 : Stereographic projection", "schema": { "type": "string", "enum": [ "EPSG:3395", "EPSG:3857", "EPSG:9840", "EPSG:9820", "EPSG:9825", "ESRI:54026" ], "example": "EPSG:3395", "default": "EPSG:3395" } }, { "in": "query", "name": "map-center", "description": "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.", "schema": { "type": "array", "items": { "type": "number", "minimum": -180, "maximum": 180, "example": [ 0, 0 ] }, "minItems": 2, "maxItems": 2, "default": [ 0, 0 ] } }, { "in": "query", "name": "map-theme", "description": "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'.\n - land-small : show the lands and major islands. Suitable for schematic map of the eclipse\n - land-medium : show the lands and major islands. Suitable for detailed map of the eclipse\n - country-small : show the country boundaries. Suitable for schematic map of the eclipse\n - country-medium : show the country boundaries. Suitable for detailed map of the eclipse", "schema": { "type": "string", "enum": [ "land-small", "land-medium", "country-small", "country-medium" ], "example": "land-small", "default": "land-small" } }, { "in": "query", "name": "map-zoom", "description": "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.", "schema": { "type": "number", "minimum": 1, "maximum": 20, "example": 1, "default": 1 } }, { "in": "query", "name": "map-labels", "description": "Display the label of the lines of the events on the map.\n - none : no label is displayed.\n - en : english labels (P1, U1, U2, U3, U4, P4) are displayed.\n - fr : french labels (P1, O1, T1, T2, O2, P2) are displayed.", "schema": { "type": "string", "enum": [ "none", "en", "fr" ], "example": "none", "default": "none" } }, { "in": "query", "name": "map-meridian-zenith", "description": "Show, as a solid line on the map, the meridian where the moon is at the zenith at the greatest event.", "schema": { "type": "boolean", "example": false, "default": false } } ], "responses": { "200": { "description": "Lunar or solar eclipses", "content": { "application/json": { "schema": { "type": "object", "required": [ "response", "link", "request" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "request": { "type": "object", "description": "parameters of the current computation", "properties": {} }, "response": { "type": "object", "required": [ "calendar", "lunareclipse", "timescale" ], "properties": { "calendar": { "description": "All dates and times of the request or response are expressed in this calendar", "type": "string" }, "timescale": { "description": "Time scale of the computed data", "type": "string" }, "description": { "description": "Description of the fields of the object data or lunareclipse", "type": "object", "properties": {} }, "unit": { "description": "Units of the fields of the object data or lunareclipse", "type": "object", "properties": {} }, "lunareclipse": { "description": "Array of the lunar eclipses", "type": "array", "items": { "type": "object", "required": [ "type", "magnitude", "duration", "radius", "events", "calendarDate", "link" ], "properties": { "type": { "description": "Type of the lunar eclipse.\n - PenumbralEclipse : Moon passes through Earth's penumbra.\n - PartialEclipse : Only part of the Moon's surface is obscured by Earth's umbra.\n - TotalEclipse : Earth's umbra obscures all of the Moon's surface.\n - TotalPenumbralEclipse : Entire disk of the Moon is immersed in the penumbral shadow", "type": "string", "enum": [ "PenumbralEclipse", "PartialEclipse", "TotalEclipse", "TotalPenumbralEclipse" ] }, "calendarDate": { "description": "Calendar date of the eclipse, truncated to the day (YYYY-MM-DD). The calendar of this date depends on the response property *{calendar}*.", "type": "string" }, "magnitude": { "description": "Greatest magnitude of the lunar eclipse", "type": "number" }, "duration": { "description": "Duration of each phase of the lunar eclipse", "type": "object", "required": [ "penumbral", "partial", "total" ], "properties": { "penumbral": { "description": "Interval in HH:MM:SS between the beginning and the end of the penumbral phase", "type": "string", "nullable": true }, "partial": { "description": "Interval in HH:MM:SS between the beginning and the end of the partial phase", "type": "string", "nullable": true }, "total": { "description": "Interval in HH:MM:SS between the beginning and the end of the total phase", "type": "string", "nullable": true } } }, "radius": { "description": "Radius of the shadows", "type": "object", "required": [ "penumbra", "umbra" ], "properties": { "penumbral": { "description": "Radius of the penumbral shadow", "$ref": "#/components/schemas/angle" }, "umbra": { "description": "Radius of the umbral shadow", "$ref": "#/components/schemas/angle" } } }, "events": { "description": "Different instants of the eclipses", "type": "object", "required": [ "greatest" ], "properties": { "greatest": { "description": "Instant of the greatest eclipse and the position, apparent semi-diameter, horizontal parallax of the Sun and the Moon", "nullable": true, "$ref": "#/components/schemas/lunareclipse_contact" }, "P1": { "description": "Instant of first exterior tangency of Moon with Penumbra. Beginning of the penumbral eclipse", "nullable": true, "$ref": "#/components/schemas/lunareclipse_contact" }, "U1": { "description": "Instant of first exterior tangency of Moon with the umbra. Beginning of the partial umbral eclipse", "nullable": true, "$ref": "#/components/schemas/lunareclipse_contact" }, "U2": { "description": "Instant of first interior tangency of Moon with the umbra. Beginning of the total umbral eclipse", "nullable": true, "$ref": "#/components/schemas/lunareclipse_contact" }, "U3": { "description": "Instant of last interior tangency of Moon with the umbra. End of the total umbral eclipse", "nullable": true, "$ref": "#/components/schemas/lunareclipse_contact" }, "U4": { "description": "Instant of last exterior tangency of Moon with the umbra. End of the partial umbral eclipse", "nullable": true, "$ref": "#/components/schemas/lunareclipse_contact" }, "P4": { "title": "Instant of last exterior tangency of Moon with the penumbra. End of the penumbral eclipse", "nullable": true, "$ref": "#/components/schemas/lunareclipse_contact" } } }, "link": { "type": "object", "required": [ "self", "image" ], "properties": { "self": { "description": "uri of the data of the eclipse", "type": "string", "format": "uri" }, "image": { "description": "uri of the image of the eclipse", "type": "string", "format": "uri" }, "video": { "description": "uri of the video of the eclipse", "type": "string", "format": "uri" } } } } } }, "data": { "description": "Array of the solar eclipses", "type": "array", "items": { "type": "object", "required": [ "type", "magnitude", "duration", "obscuration", "events", "calendarDate", "physicalData", "link" ], "properties": { "type": { "description": "Type of the solar eclipse.\n\n For the general circumstances :\n - NonCentralPartialEclipse : partial solar eclipse\n - NonCentralHybridEclipse : non central annular or total solar eclipse\n - NonCentralTotalEclipse : non central total solar eclipse\n - NonCentralAnnularEclipse : non central annular solar eclipse\n - CentralHybridEclipse : central annular or total solar eclipse\n - CentralTotalEclipse : central total solar eclipse\n - CentralAnnularEclipse : central annular solar eclipse\n\n For the local circumstances :\n - ObserverPartialEclipse : partial solar eclipse\n - ObserverTotalEclipse : total eclipse\n - ObserverAnnularEclipse : annular eclipse", "type": "string", "enum": [ "NonCentralPartialEclipse", "NonCentralHybridEclipse", "NonCentralTotalEclipse", "NonCentralAnnularEclipse", "CentralHybridEclipse", "CentralTotalEclipse", "CentralAnnularEclipse", "ObserverPartialEclipse", "ObserverTotalEclipse", "ObserverAnnularEclipse" ] }, "calendarDate": { "description": "Calendar date of the eclipse, truncated to the day (YYYY-MM-DD). The calendar of this date depends on the response property *{calendar}*.", "type": "string" }, "magnitude": { "description": "Fraction of the linear diameter of the Sun covered by the Moon at the greatest event", "type": "number" }, "obscuration": { "description": "Percentage of the area of the apparent solar disk covered by the Moon at the greatest event, available only for the local circumstances", "type": "number", "nullable": true }, "duration": { "description": "Duration of each phase of the solar eclipse", "type": "object", "required": [ "penumbral", "umbral" ], "properties": { "penumbral": { "description": "Interval in HH:MM:SS between the beginning and the end of the penumbral phase", "type": "string", "nullable": true }, "umbral": { "description": "Interval in HH:MM:SS between the beginning and the end of the partial phase", "type": "string", "nullable": true } } }, "physicalData": { "description": "Physical data of the bodies", "type": "object", "required": [ "Sun", "Moon", "Earth" ], "properties": { "Sun": { "description": "Physical data of the Sun", "type": "object", "required": [ "radius" ], "properties": { "radius": { "description": "Equatorial radius of the Sun", "type": "number" } } }, "Moon": { "description": "Physical data of the Moon", "type": "object", "required": [ "radius" ], "properties": { "radius": { "description": "Equatorial radius of the Moon", "type": "number" } } }, "Earth": { "description": "Physical data of the Earth", "type": "object", "required": [ "radius", "inverseFlattening" ], "properties": { "radius": { "description": "Equatorial radius of the Earth", "type": "number" }, "inverseFlattening": { "description": "Inverse of the flattening of the Earth's ellipsoid", "type": "number" } } } } }, "events": { "description": "Different instants of the eclipses", "type": "object", "required": [ "greatest", "P1", "P4" ], "properties": { "greatest": { "title": "Instant of the greatest eclipse and the position of the Sun and the Moon and on the Earth", "nullable": true, "$ref": "#/components/schemas/solareclipse_contact" }, "P1": { "description": "Instant of first exterior tangency of the Penumbra with the surface of the Earth", "nullable": true, "$ref": "#/components/schemas/solareclipse_contact" }, "P2": { "description": "Instant of first interior tangency of the Penumbra with the surface of the Earth", "nullable": true, "$ref": "#/components/schemas/solareclipse_contact" }, "U1": { "description": "Instant of first exterior tangency of umbra with the surface of the Earth.", "nullable": true, "$ref": "#/components/schemas/solareclipse_contact" }, "C1": { "description": "Instant of first contact of the umbral axis with the surface of the Earth.", "nullable": true, "$ref": "#/components/schemas/solareclipse_contact" }, "U2": { "description": "Instant of first interior tangency of umbra with the surface of the Earth.", "nullable": true, "$ref": "#/components/schemas/solareclipse_contact" }, "U3": { "description": "Instant of last interior tangency of umbra with the surface of the Earth.", "nullable": true, "$ref": "#/components/schemas/solareclipse_contact" }, "C2": { "description": "Instant of last contact of the umbral axis with the surface of the Earth.", "nullable": true, "$ref": "#/components/schemas/solareclipse_contact" }, "U4": { "description": "Instant of last exterior tangency of umbra with the surface of the Earth.", "nullable": true, "$ref": "#/components/schemas/solareclipse_contact" }, "P3": { "description": "Instant of last interior tangency of the Penumbra with the surface of the Earth", "nullable": true, "$ref": "#/components/schemas/solareclipse_contact" }, "P4": { "description": "Instant of last exterior tangency of the Penumbra with the surface of the Earth", "nullable": true, "$ref": "#/components/schemas/solareclipse_contact" } } }, "link": { "type": "object", "required": [ "self", "image" ], "properties": { "self": { "description": "uri of the data of the eclipse", "type": "string", "format": "uri" }, "image": { "description": "uri of the image of the eclipse", "type": "string", "format": "uri" }, "video": { "description": "uri of the video of the eclipse", "type": "string", "format": "uri" } } } } } } } } }, "example": "EXAMPLELUNARECLIPSE" } }, "application/postscript": { "schema": { "description": "Map of the eclipse as postscript image", "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "description": "Map of the eclipse as pdf image", "type": "string", "format": "binary" } }, "image/svg+xml": { "schema": { "description": "Map of the eclipse as svg image", "type": "string" } }, "video/mp4": { "schema": { "description": "Animation of the eclipse as mp4 video", "type": "string", "format": "binary" } }, "video/webm": { "schema": { "description": "Animation of the eclipse as webm video", "type": "string", "format": "binary" } } } }, "202": { "description": "The request has been accepted for processing, but the processing has not been completed.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "response" ], "properties": { "response": { "type": "object", "required": [ "estimatedDelay", "workProgress" ], "properties": { "estimatedDelay": { "description": "Estimation of the delay, expressed in seconds, to obtain the result of the processing", "type": "number" }, "workProgress": { "description": "Current amount of work that has been completed for this processing. The value 0 means that no work has been done and a value of 100 means that the processing is almost finished", "type": "number", "minimum": 0, "maximum": 100 } } } } } } } }, "206": { "description": "Partial content of the movie of the eclipses", "content": { "video/mp4": { "schema": { "description": "Animation of the eclipse as mp4 video", "type": "string", "format": "binary" } }, "video/webm": { "schema": { "description": "Animation of the eclipse as webm video", "type": "string", "format": "binary" } } } }, "500": { "$ref": "#/components/responses/500" }, "416": { "$ref": "#/components/responses/416" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/phenomena/rts/{body}/{date}/{terrestrialobserver}": { "get": { "summary": "Rise, transits and set", "description": "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.\n\nA 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.\n\nThe 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.\n\nThe elevation of the body during the transit is :\n - apparent elevation if the value is positive or zero, the object is visible taking into account the refraction of the atmosphere.\n - true elevation, otherwise, the object is invisible, even taking into account the refraction of the atmosphere.\n\nIf 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.\n\nExamples:\n - Get the rise, lower and upper transit, and set of Sun for an observer located at Paris on July 5th, 2020 in the timescale UTC :\n __URL__/v1/phenomena/rts/10/2020-07-05/48.8534,2.3488,39\n - Get the rise, lower and upper transit, and set of Sun for an observer located at Paris on July 5th, 2020 in the timescale UTC + 2 hours :\n __URL__/v1/phenomena/rts/10/2020-07-05/48.8534,2.3488,39?timescale=UTC%2B02:00\n\n - Get the rise, lower and upper transits, and set of Sun and twlights for an observer located at the observatory of Nice on July 5th, 2020 :\n __URL__/v1/phenomena/rts/10/2020-07-05/obscode:020?twilight=true\n - Get the rise, lower and upper transits and set of Moon for an observer located at Paris between September 21th, 2020 and September 23rd, 2020 :\n __URL__/v1/phenomena/rts/301/2021-09-20/48.8534,2.3488,39?nbd=3\n - Get the rise, lower and upper transits and set of Sun for an observer located at Paris between July 5th, 2020 and July 8th, 2020 :\n __URL__/v1/phenomena/rts/10/2020-07-05/48.8534,2.3488,39?nbd=8\n\nCapabilities : __URL__/v1/phenomena/rts/capability", "parameters": [ { "in": "path", "name": "body", "description": "Observed body:\n - NAIF identification number of the observed body ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html))\n - identifier of an observed star : HIP number, WDS identifier.\n\nexample:\n - 4 for Mars\n - HIP-49669 for Regulus.", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,9}|HIP-\\d{1,6}$", "example": "10", "default": "10" } }, { "in": "path", "name": "date", "description": "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.\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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": true, "schema": { "type": "string", "pattern": "^(gregorian,|julian,)?-?\\d{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[12]\\d|3[01])$", "example": "__CURRENTYEAR__-01-10", "default": "2020-01-10" } }, { "in": "path", "name": "terrestrialobserver", "description": "Location of the observer on the Earth", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/observer_terrestrial_observatory_code" }, { "$ref": "#/components/schemas/observer_terrestrial_longitude_latitude_altitude" } ], "example": [ 48, 150, 0 ] } }, { "in": "query", "name": "step", "description": "Step between the dates to compute, expressed in day", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 1, "default": 1 } }, { "in": "query", "name": "nbd", "description": "Number of dates to compute", "schema": { "type": "integer", "minimum": 1, "maximum": 730, "example": 1, "default": 1 } }, { "in": "query", "name": "twilight", "description": "Provide or not the dawn and dusk timings for the Sun. For other bodies, this boolean value is ignored.", "schema": { "type": "boolean", "example": false, "default": false } }, { "in": "query", "name": "group-by", "description": "Group the results into different arrays according different orders.\n - body-calendarDate : The results are grouped by body and then grouped by the same calendar day.", "schema": { "type": "string", "enum": [ "body-calendarDate" ], "example": "body-calendarDate", "default": "body-calendarDate" } }, { "in": "query", "name": "timescale", "required": true, "description": "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.\n\nThe supported timescales are \n - UTC\n - UTC\u00b1hh:mm , where \u00b1hh:mm is the difference in hours and minutes from UTC. The plus sign math symbol, in the character \u00b1, must be encoded using the characters %2B.\n - UT1\n\nFor all dates expressed in UTC or UTC\u00b1hh:mm after the last leap second, the difference between the timescale UTC and TAI is constant.\n\nThe 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.", "schema": { "$ref": "#/components/schemas/timescaleUTCUT1" } } ], "responses": { "200": { "description": "Rise, upper transit, set", "content": { "application/json": { "schema": { "type": "object", "required": [ "response", "link", "request" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "request": { "type": "object", "description": "parameters of the current computation", "properties": {} }, "response": { "type": "object", "required": [ "calendar", "data", "timescale" ], "properties": { "calendar": { "description": "Calendar date of the computed data", "type": "string" }, "timescale": { "description": "Time scale of the computed data", "type": "string" }, "description": { "description": "Description of the fields of the object data", "type": "object", "properties": {} }, "unit": { "description": "Units of the fields of the object data", "type": "object", "properties": {} }, "data": { "description": "Array of all events", "type": "array", "items": { "description": "Array of the events for each body", "type": "object", "properties": { "{body}": { "description": "Array of the rise, upper transit and set of the {body}", "type": "array", "items": { "type": "object", "required": [ "calendarDate", "rise", "set", "upperTransit", "lowerTransit" ], "properties": { "calendarDate": { "description": "calendar date of the events, truncated to the day (YYYY-MM-DD)", "type": "string" }, "rise": { "description": "Instant and azimuth of the rises. The array is empty if no event occurs.", "type": "array", "items": { "type": "object", "required": [ "date", "coord" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "coord": { "description": "Azimuth from North of the rise", "$ref": "#/components/schemas/angle" } } } }, "set": { "description": "Instant and azimuth of the set. The array is empty if no event occurs.", "type": "array", "items": { "type": "object", "required": [ "date", "coord" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "coord": { "description": "Azimuth from North of the set", "$ref": "#/components/schemas/angle" } } } }, "upperTransit": { "description": "Instant and elevation of the upper transits. The array is empty if no event occurs. The coordinate of the upper transit is the apparent elevation if its value is positive or zero (refracted coordinate), otherwise true elevation (without refraction).", "type": "array", "items": { "type": "object", "required": [ "date", "coord" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "coord": { "description": "Elevation of the body at the upper transit. The coordinate of the upper transit is the apparent elevation if its value is positive or zero (refracted coordinate), otherwise true elevation (without refraction).", "$ref": "#/components/schemas/angle" } } } }, "lowerTransit": { "description": "Instant and elevation of the lower transits. The array is empty if no event occurs. . The coordinate of the upper transit is the apparent elevation if its value is positive or zero (refracted coordinate), otherwise true elevation (without refraction).", "type": "array", "items": { "type": "object", "required": [ "date", "coord" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "coord": { "description": "Elevation of the body at the lower transit. The coordinate of the upper transit is the apparent elevation if its value is positive or zero (refracted coordinate), otherwise true elevation (without refraction).", "$ref": "#/components/schemas/angle" } } } }, "astronomicalDawn": { "nullable": true, "description": "Instant of the astronomical dawn and azimuth of the Sun at this instant. The value is null if the {body} is not the Sun. The array is empty if no event occurs.", "type": "array", "items": { "type": "object", "required": [ "date", "coord" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "coord": { "description": "Elevation of the body at the upper transit", "$ref": "#/components/schemas/angle" } } } }, "nauticalDawn": { "nullable": true, "description": "Instant of the nautical dawn and azimuth of the Sun at this instant. The value is null if the {body} is not the Sun. The array is empty if no event occurs.", "type": "array", "items": { "type": "object", "required": [ "date", "coord" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "coord": { "description": "Elevation of the body at the upper transit", "$ref": "#/components/schemas/angle" } } } }, "civilDawn": { "nullable": true, "description": "Instant of the civil dawn and azimuth of the Sun at this instant. The value is null if the {body} is not the Sun. The array is empty if no event occurs.", "type": "array", "items": { "type": "object", "required": [ "date", "coord" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "coord": { "description": "Elevation of the body at the upper transit", "$ref": "#/components/schemas/angle" } } } }, "astronomicalDusk": { "nullable": true, "description": "Instant of the astronomical dusk and azimuth of the Sun at this instant. The value is null if the {body} is not the Sun. The array is empty if no event occurs.", "type": "array", "items": { "type": "object", "required": [ "date", "coord" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "coord": { "description": "Elevation of the body at the upper transit", "$ref": "#/components/schemas/angle" } } } }, "nauticalDusk": { "nullable": true, "description": "Instant of the nautical dusk and azimuth of the Sun at this instant. The value is null if the {body} is not the Sun. The array is empty if no event occurs.", "type": "array", "items": { "type": "object", "required": [ "date", "coord" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "coord": { "description": "Elevation of the body at the upper transit", "$ref": "#/components/schemas/angle" } } } }, "civilDusk": { "nullable": true, "description": "Instant of the civil dusk and azimuth of the Sun at this instant. The value is null if the {body} is not the Sun. The array is empty if no event occurs.", "type": "array", "items": { "type": "object", "required": [ "date", "coord" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "coord": { "description": "Elevation of the body at the upper transit", "$ref": "#/components/schemas/angle" } } } } } } } } } } } } }, "example": "EXAMPLESUNRTS" } } } }, "500": { "$ref": "#/components/responses/500" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/phenomena/satellites/{body}": { "get": { "summary": "Phenomena of natural satellites", "description": "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 ).\n\nThe predicted instants are the instant of the first and last contact ('speck') of the phenomena.\n\n The list of phenomena is returned to the client encoded in *json* format.\n\nExamples :\n\n - Get the phenomena of the jovian satellites between the March 3th, 2021 and March 6th, 2021, expressed in the timescale UTC, using the theories NOE for the satellites : __URL__/v1/phenomena/satellites/599?date=2021-03-03T00:00:00.000×cale=UTC&nbd=3&theory=INPOP19A,NOE-5-2021", "parameters": [ { "in": "path", "name": "body", "description": "NAIF identification number of the observed body ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html))", "required": true, "schema": { "type": "integer", "enum": [ 599, 699, 799, 920004337 ], "example": 599 } }, { "in": "query", "name": "date", "required": true, "description": "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*.", "schema": { "oneOf": [ { "type": "number", "description": "Julian day, valid only if the parameter *calendar* is 'JD'", "minimum": 0.0, "example": 2459276.8486059606 }, { "type": "string", "format": "date-time", "description": "Gregorian or Julian calendar date, valid only if the parameter *calendar* is 'gregorian' or 'julian'. This calendar date is expressed using the notation YYYY-MM-DDTHH:MM:SS.SSS. The default value is the current day.", "example": "2021-01-01T00:00:01.000" } ] } }, { "in": "query", "name": "nbd", "description": "Number of dates to compute", "schema": { "type": "integer", "minimum": 1, "maximum": 730, "example": 1, "default": 1 } }, { "in": "query", "name": "calendar", "description": "All dates and times of the request or response are expressed in this calendar.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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.\n- 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.", "schema": { "$ref": "#/components/schemas/calendar" } }, { "in": "query", "name": "timescale", "description": "All dates and times of the request or response are expressed in this timescale.\n\nBefore 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.\n\nThe 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.", "schema": { "$ref": "#/components/schemas/timescale" } }, { "in": "query", "name": "theory", "description": "Planetary and satellites theories used for the computations ([details](theories/))", "schema": { "$ref": "#/components/schemas/theory" }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Phenomena of satellites/satellites and satellites/planet", "content": { "application/json": { "schema": { "description": "predicted phenomena of the satellites", "type": "object", "required": [ "response", "link", "request" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "request": { "type": "object", "description": "parameters of the current computation", "properties": {} }, "response": { "type": "object", "required": [ "calendar", "data", "timescale" ], "properties": { "calendar": { "description": "All dates and times of the request or response are expressed in this calendar", "type": "string" }, "timescale": { "description": "Time scale of the computed data", "type": "string" }, "description": { "description": "Description of the fields of the object data", "type": "object", "properties": {} }, "unit": { "description": "Units of the fields of the object data", "type": "object", "properties": {} }, "data": { "description": "Array of all phenomena", "type": "array", "items": { "description": "Phenomena", "type": "object", "required": [ "countLocalGreatest", "duration", "eclipsingBody", "eclipsedBody", "mutualPhenomena", "type", "subType", "events" ], "properties": { "type": { "description": "Type of the phenomena", "oneOf": [ { "description": "Type of the phenomena for a mutual phenomena", "type": "string", "enum": [ "Eclipse", "Occultation" ] }, { "description": "Type of the phenomena for between a satellite and a planet", "type": "string", "enum": [ "Eclipse", "Occultation", "Shadow", "Transit" ] } ] }, "subType": { "description": "Kind of eclipse or occultation", "oneOf": [ { "description": "Kind of eclipse or occultation for a mutual phenomena", "type": "string", "enum": [ "Partial", "Total", "Annular", "Penumbral" ] }, { "description": "Kind of event for a phenomena between a satellite and a planet", "type": "string", "enum": [ "Disappearance", "Reappearance", "Egress", "Ingress" ] } ] }, "duration": { "description": "Interval in minutes between the beginning and the end", "type": "number" }, "eclipsingBody": { "description": "Eclipsing or occulting body", "type": "integer" }, "eclipsedBody": { "description": "Eclipsed or occulted body", "type": "integer" }, "mutualPhenomena": { "description": "true if the phenomena is between two satellites", "type": "boolean" }, "countLocalGreatest": { "description": "Number of greatest event between the beginning and the end of the phenomena", "type": "integer" }, "deltaCombinedMagnitude": { "nullable": true, "description": "Combined magnitude of the pair of satellites in the phenomena", "type": "number" }, "dropNormalizedFlux": { "nullable": true, "description": "Percentage of the drop of the normalized flux at the maximum of the phenomena", "type": "number" }, "impactFactor": { "nullable": true, "description": "Equals to zero if the event is a central passage of satellite through the shadow or through the apparent disk of another satellite. This factor equals to unit in the case of a grazing event", "type": "number" }, "events": { "description": "Events of the phenomena", "type": "object", "required": [ "begin", "end" ], "properties": { "begin": { "description": "Instant of the first contact of the phenomena", "type": "object", "$ref": "#/components/schemas/phenomena_satellites_events" }, "end": { "description": "Instant of the last contact of the phenomena", "type": "object", "$ref": "#/components/schemas/phenomena_satellites_events" }, "greatest": { "description": "Instant of the greatest drop of the normalized flux", "type": "object", "$ref": "#/components/schemas/phenomena_satellites_events" } } } } } } } } }, "example": "EXAMPLEJUPITERPHENOMENA" } } } }, "500": { "$ref": "#/components/responses/500" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/phenomena/moonphases": { "get": { "summary": "Moon phases", "description": "Get all moon phases phenomena for a given date. The instants of the events are given in the timescale UTC by default.\n\nA response, which contains the information about all phenomena, is returned to the client encoded in *json* format.\n\nExamples:\n - Get all phases of the moon for January, 2022 :\n __URL__/v1/phenomena/moonphases?year=2022&month=1 \n\nCapabilities : __URL__/v1/phenomena/moonphases/capability", "parameters": [ { "in": "query", "name": "year", "description": "Requested calendar year with format YYYY", "required": true, "schema": { "description": "Calendar year YYYY", "type": "integer", "example": 2022, "default": 2022 } }, { "in": "query", "name": "month", "description": "Requested calendar month with format MM", "schema": { "description": "Calendar date MM", "type": "integer", "minimum": 1, "maximum": 12 } }, { "in": "query", "name": "timescale", "description": "All dates and times of the request or response are expressed in this timescale.\n\nThe supported timescales are \n - UTC\n - UTC\u00b1hh:mm , where \u00b1hh:mm is the difference in hours and minutes from UTC. The plus sign math symbol, in the character \u00b1, must be encoded using the characters %2B.\n - UT1\n\nBefore 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.\n\nThe 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.", "required": true, "schema": { "$ref": "#/components/schemas/timescaleUTCUT1" } }, { "in": "query", "name": "calendar", "description": "All dates and times of the request or response are expressed in this calendar.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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": true, "schema": { "$ref": "#/components/schemas/calendarJulianOrGregorian" } } ], "responses": { "200": { "description": "List of selected phenomena", "content": { "application/json": { "schema": { "description": "Data of selected phenomena", "type": "object", "required": [ "response", "link", "request" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "request": { "type": "object", "description": "parameters of the current computation", "properties": {} }, "response": { "type": "object", "required": [ "data", "timescale" ], "properties": { "timescale": { "description": "Time scale of the computed data", "type": "string" }, "description": { "description": "Description of the fields of the object data", "type": "object", "properties": {} }, "unit": { "description": "Units of the fields of the object data", "type": "object", "properties": {} }, "data": { "description": "Array of the moon phases", "type": "array", "items": { "type": "object", "required": [ "date", "moonPhase" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "moonPhase": { "description": "name of the phase", "type": "string" } } } } } } }, "example": "EXAMPLEMOONPHASES" } } } }, "500": { "$ref": "#/components/responses/500" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/phenomena/equinoxessolstices/{body}": { "get": { "summary": "Equinoxes and Solstices", "description": "Get all equinoxes and solstices on the Earth and on the planet Mars over a given timespan.\nThe 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\u00b0, 90\u00b0, 180\u00b0, and 270\u00b0 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.\n\nA response, which contains the information about all phenomena, is returned to the client encoded in json format.\n\nIf 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.\n\nExamples: \n - Get all the equinoxes and solstices on the Earth over the years 2022-2023 : __URL__/v1/phenomena/equinoxessolstices/399?year=2022&nbd=2\n - Get all the equinoxes and solstices on the Earth over the years 1500-1510 in the timescale UT1 and julian calendar : __URL__/v1/phenomena/equinoxessolstices/399?year=1500&nbd=10×cale=UT1&calendar=julian\n - Get all the equinoxes and solstices on the planet Mars over the years 2000-2002 in the timescale UTC : __URL__/v1/phenomena/equinoxessolstices/499?year=2000&nbd=3", "parameters": [ { "in": "path", "name": "body", "description": "NAIF identification number of the planet ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html)) :\n - 399 for the Earth\n - 499 for the planet Mars.", "required": true, "schema": { "type": "integer", "enum": [ 399, 499 ], "example": 399, "default": 399 } }, { "in": "query", "name": "year", "description": "Requested calendar year with format YYYY", "required": true, "schema": { "description": "Calendar year YYYY", "type": "integer", "example": 2022, "default": 2022 } }, { "in": "query", "name": "timescale", "description": "All dates and times of the request or response are expressed in this timescale.\n\nThe supported timescales are \n - UTC\n - UTC\u00b1hh:mm , where \u00b1hh:mm is the difference in hours and minutes from UTC. The plus sign math symbol, in the character \u00b1, must be encoded using the characters %2B.\n - UT1\n\nBefore 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.\n\nThe 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.", "required": true, "schema": { "$ref": "#/components/schemas/timescaleUTCUT1" } }, { "in": "query", "name": "calendar", "required": true, "description": "All dates and times of the request or response are expressed in this calendar.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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.", "schema": { "$ref": "#/components/schemas/calendarJulianOrGregorian" } }, { "in": "query", "name": "nbd", "description": "The number of years to compute", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "example": 1, "default": 1 } } ], "responses": { "200": { "description": "Equinoxes and solstices on the planet Earth or Mars", "content": { "application/json": { "schema": { "description": "Equinoxes and solstices on the planet Earth or Mars", "type": "object", "required": [ "response", "link", "request" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "request": { "type": "object", "description": "parameters of the current computation", "properties": {} }, "response": { "type": "object", "required": [ "data", "unit" ], "properties": { "description": { "description": "Description of the fields of the object data", "type": "object", "properties": {} }, "data": { "description": "Array of equinoxes and solstices", "type": "array", "items": { "type": "object", "required": [ "date", "phenomena" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "phenomena": { "description": "Event type", "enum": [ "VernalEquinox", "SummerSolstice", "AutumnalEquinox", "WinterSolstice" ] } } } } } } }, "example": "EXAMPLEEQUINOXSOLSTICE" } } } }, "500": { "$ref": "#/components/responses/500" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/positions/{body}": { "get": { "summary": "Positions", "description": "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*.\n\nA response, which contains the information about the requested position, is returned to the client encoded in *json* or *text* format.\n\nIf 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.\n\nExamples:\n - Get the apparent position of Venus for an observer located at the Observatory of Paris on October 30th, 2020 at 12pm in json format:\n __URL__/v1/positions/299?date=2020-10-30T12:00:00&observer=obscode:007&step=1D&nbd=1&frame=TrueOfDate×cale=UTC&reference=origin&places=apparent&quantities=cart,radec,azel,dist\n - Get the apparent position of Venus for an observer located at Salmanca on the Julian calendar date July 24th, 1476 at 12pm UT1 in json format:\n __URL__/v1/positions/299?date=1476-07-24T12:00:00&observer=48.96,-5.65,0&step=1D&nbd=1&frame=TrueOfDate&calendar=julian×cale=UT1&reference=origin&places=apparent&quantities=cart,radec,azel,dist\n - Get the apparent position of Moon for an observer located at Salmanca on the Julian date 2260363.0 TT in json format:\n __URL__/v1/positions/299?date=2260363.0&observer=48.96,-5.65,0&step=1D&nbd=1&frame=TrueOfDate&calendar=JD×cale=TT&reference=origin&places=apparent&quantities=cart,radec,azel,dist\n - Get the apparent position of Venus for an observer located at the Observatory of Paris on October 30th, 2020 at 12pm in text format:\n __URL__/v1/positions/299?date=2020-10-30T12:00:00&observer=obscode:007&step=1D&nbd=1&frame=TrueOfDate×cale=UTC&reference=origin&places=apparent&quantities=cart,radec,azel,dist&format=text\n - Get the astrometric position of the satellite Io relative to Jupiter for an observer located at Paris between October 1st, 2020 and October 20rd, 2020:\n __URL__/v1/positions/501?date=2020-10-01T00:00:00&observer=48.8534,2.3488,39&step=1D&nbd=3&frame=MeanJ2000×cale=UTC&reference=599&places=astrometric&quantities=tancart,tanaz\n - Get the geometric position of the Moon for an observer located at the geocenter between September 21th, 2020 and September 23rd, 2020 :\n __URL__/v1/positions/301?date=2021-09-20T00:00:00&observer=399&step=1D&nbd=3&frame=BCRF×cale=UTC&reference=origin&places=geometric&quantities=cart\n - Get the apparent position of Jupiter for an observer located at Paris between July 5th, 2020 and July 8th, 2020 :\n __URL__/v1/positions/5?date=2020-07-05T20:05:33&observer=48.8534,2.3488,39&step=1D&nbd=3&frame=TrueOfDate×cale=UTC&reference=origin&places=apparent&quantities=cart,radec,azel,dist\n - Get the position of Earth for an observer located on the Moon on October 30th, 2020 at 12pm:\n __URL__/v1/positions/399?date=2020-10-30T12:00:00&observer=301&step=1D&nbd=1&frame=TrueOfDate×cale=UTC&reference=origin&places=apparent&quantities=cart,radec,dist\n\nCapabilities : __URL__/v1/positions/capability", "parameters": [ { "in": "path", "name": "body", "description": "Observed body:\n - NAIF identification number of the observed body ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html))\n - identifier of an observed star : HIP number, WDS identifier.\n\nexample:\n - 4 for Mars\n - HIP-49669 for Regulus.", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,9}|HIP-\\d{1,6}$", "example": "10", "default": "10" } }, { "in": "query", "name": "reference", "description": "The axis or point used as the origin of the absolute or relative coordinates.\n\nAbsolute 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": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/reference_string" }, { "$ref": "#/components/schemas/reference_naif_identification" } ] } }, { "in": "query", "name": "date", "required": true, "description": "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*.", "schema": { "oneOf": [ { "type": "number", "description": "Julian day, valid only if the parameter *calendar* is 'JD'", "minimum": 0.0, "example": 2459276.8486059606 }, { "type": "string", "format": "date-time", "description": "Gregorian or Julian calendar date, valid only if the parameter *calendar* is 'gregorian' or 'julian'. This calendar date is expressed using the notation YYYY-MM-DDTHH:MM:SS.SSS", "example": "2021-01-01T00:00:01.000" } ] } }, { "in": "query", "name": "timescale", "description": "All dates and times of the request or response are expressed in this timescale.\n\nBefore 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.\n\nThe 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.", "schema": { "$ref": "#/components/schemas/timescale" } }, { "in": "query", "name": "calendar", "description": "All dates and times of the request or response are expressed in this calendar.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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.\n- 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.", "schema": { "$ref": "#/components/schemas/calendar" } }, { "in": "query", "name": "step", "description": "Step between the dates to compute, expressed in day, hour, minute or second. The suffix letter may be :\n - D : day\n - H : hour\n - M : minute\n - S : second", "schema": { "$ref": "#/components/schemas/step_string" }, "required": true }, { "in": "query", "name": "nbd", "description": "Number of dates to compute.", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "example": 1, "default": 1 } }, { "in": "query", "name": "observer", "required": true, "description": "Location of the observer.", "schema": { "oneOf": [ { "$ref": "#/components/schemas/observer_terrestrial_observatory_code" }, { "$ref": "#/components/schemas/observer_terrestrial_longitude_latitude_altitude" }, { "$ref": "#/components/schemas/observer_naif_identification" } ] } }, { "in": "query", "name": "frame", "description": "Reference frame. The coordinates are expressed in this frame.\n\n - 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.\n - GCRF : Geocentric Celestial Reference Frame; origin is the Earth's center of mass, axes are aligned with International Celestial Reference Frame.\n - 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.\n - MeanJ2000 : Mean Equinox/Mean Equator J2000; XY plane is the mean equator J2000 ; origin is the center of mass of the body.\n - EclipticJ2000 : Mean Equinox/Mean Ecliptic J2000; XY plane is the mean ecliptic J2000 ; origin is the center of mass of the body\n - 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\n - 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.\n - GTRF : the Geocentric Terrestrial Reference Frame, same as *BodyFixed* for the Earth.\n - 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.\n\nThe precession/nutation model IAU2000A and EOP series C04 are applied to the frames affected by the precession and nutation, such as TrueOfDate or BodyFixed. ", "schema": { "$ref": "#/components/schemas/frame" } }, { "in": "query", "name": "theory", "description": "Planetary and satellites theories used for the computations ([details](theories/))", "schema": { "$ref": "#/components/schemas/theory" }, "style": "form", "explode": false }, { "in": "query", "name": "places", "description": "Applied corrections to compute the positions of the celestial bodies and the observer.\n\n - 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.\n - 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.\n - 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.", "schema": { "$ref": "#/components/schemas/places" } }, { "in": "query", "name": "format", "description": "The response format. The default response format is given by the header request Accept. If format is given, the header request Accept is ignored.", "schema": { "$ref": "#/components/schemas/format" } }, { "in": "query", "name": "coord-format", "description": "Coordinates (angles, ...) of the response are expressed in decimal or in sexagesimal.\n\n - dec : decimal angles\n - sexa : sexagesimal angles.", "schema": { "$ref": "#/components/schemas/coord-format" } }, { "in": "query", "name": "distance-unit", "description": "Distances of the response are expressed in Km or in AU.", "schema": { "$ref": "#/components/schemas/distance-unit" } }, { "in": "query", "name": "quantities", "description": "Computed quantities of the observed body.\n\n - am : Relative air mass, ratio of absolute air masses at direction target relative to that at zenith. That quantity is stored in *airMass*.\n - 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*.\n - cart : absolute cartesian coordinates, expressed in *frame*. These coordinates are stored in *cartX*, *cartY* and *cartZ*.\n - radec : absolute equatorial coordinates (right ascension and declination), expressed in *frame*. These coordinates are stored in *RA* and *DEC*.\n - lonlat : absolute ecliptic coordinates (longitude and latitude), expressed in *frame*. These coordinates are stored in *longitude* and *latitude*.\n - hadec : absolute local hour angle and declination coordinates, expressed in the equatorial frame of the observer. These coordinates are stored in *HA* and *DEC*.\n - 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*.\n - dist : distance between the observed body and the observer. That coordinate is stored in *distance*.\n - 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*.\n - 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*.\n - deltaradec : relative equatorial coordinates (right ascension and declination) to the *reference*, expressed in *frame*. These coordinates are stored in *deltaRA* and *deltaDEC*.\n - el : elongation between the observed body and the *reference* seen by the observer. That coordinate is stored in *elongation*.\n - il : illuminated fraction of a body. The body is illuminated by the Sun. That quantity is stored in *illuminatedFraction*.\n - mag : observed apparent visual magnitude. That quantity is stored in *magnitude*.\n - pan : position angle of the north pole of the body. That quantity is stored in *PAn*.\n - par : parallactic angle of the body. That quantity is stored in *parallactic*.\n - phase : observed phase of the body, illuminated by the Sun. That quantity is stored in *phase*.\n - 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*.\n - 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*.\n - 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*.\n - sspa : Position angle of the subsolar point of the body from the Celestial North. That coordinate is stored in *sspa*.\n - 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*.\n - 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*.\n - 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*.\n - 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\u00b0, 90\u00b0, 180\u00b0 and 270\u00b0 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*.\n - lt : light-time from the observed body to the observer. That coordinate is stored in *lightTime*.\n - era : Earth Rotation Angle. That coordinate is stored in *ERA*.\n - eqe : Equation of the equinoxes. That coordinate is stored in *EQE*.\n - eqo : Equation of the origins. That coordinate is stored in *EQO*.\n - eqt : Equation of Time. That coordinate is stored in *EQT*.\n - lst : Local sidereal time of the observer. That coordinate is stored in *LST*.\n - TT-TDB : Difference between the time TT and TDB (=TT-TDB). That coordinate is stored in *TT-TDB*.\n - TT-UT1 : Difference between the time TT and UT1 (=TT-UT1). That coordinate is stored in *TT-UT1*.", "schema": { "$ref": "#/components/schemas/quantities" }, "style": "form", "explode": false }, { "in": "query", "name": "theme", "description": "Predefined styles of outputs and computed quantities.\n\n - default : default theme\n - dynastvo : theme for the dynastvo services.", "schema": { "$ref": "#/components/schemas/theme" } }, { "in": "query", "name": "extraprecision", "description": "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.", "schema": { "type": "integer", "minimum": 0, "maximum": 3, "example": 1, "default": 0 } } ], "responses": { "200": { "description": "Position", "content": { "application/json": { "schema": { "description": "Data of the computed Position", "type": "object", "required": [ "response", "link", "request" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "request": { "type": "object", "description": "parameters of the current computation", "properties": {} }, "response": { "type": "object", "required": [ "data", "timescale", "calendar" ], "properties": { "calendar": { "description": "Calendar date of the computed data", "type": "string" }, "timescale": { "description": "Time scale of the computed data", "type": "string" }, "description": { "description": "Description of the fields of the object data", "type": "object", "properties": {} }, "unit": { "description": "Units of the fields of the object data", "type": "object", "properties": {} }, "data": { "type": "array", "items": { "anyOf": [ { "title": "date", "type": "string", "description": "Date ISO8601", "format": "date-time" }, { "$ref": "#/components/schemas/cartX" }, { "$ref": "#/components/schemas/cartY" }, { "$ref": "#/components/schemas/cartZ" }, { "$ref": "#/components/schemas/azimuth" }, { "$ref": "#/components/schemas/elevation" }, { "$ref": "#/components/schemas/angDiameter" }, { "$ref": "#/components/schemas/airMass" }, { "$ref": "#/components/schemas/magnitude" }, { "$ref": "#/components/schemas/phase" }, { "$ref": "#/components/schemas/longitude" }, { "$ref": "#/components/schemas/latitude" }, { "$ref": "#/components/schemas/Ls" }, { "$ref": "#/components/schemas/RA" }, { "$ref": "#/components/schemas/DEC" }, { "$ref": "#/components/schemas/LHA" }, { "$ref": "#/components/schemas/distance" }, { "$ref": "#/components/schemas/elongation" }, { "$ref": "#/components/schemas/illuminatedFraction" }, { "$ref": "#/components/schemas/X" }, { "$ref": "#/components/schemas/Y" }, { "$ref": "#/components/schemas/S" }, { "$ref": "#/components/schemas/parallactic" }, { "$ref": "#/components/schemas/PAn" }, { "$ref": "#/components/schemas/positionAngle" }, { "$ref": "#/components/schemas/deltaRA" }, { "$ref": "#/components/schemas/deltaDEC" }, { "$ref": "#/components/schemas/sopcLongitude" }, { "$ref": "#/components/schemas/sopcLatitude" }, { "$ref": "#/components/schemas/sopgLongitude" }, { "$ref": "#/components/schemas/sopgLatitude" }, { "$ref": "#/components/schemas/sopdLongitude" }, { "$ref": "#/components/schemas/sopdLatitude" }, { "$ref": "#/components/schemas/sspa" }, { "$ref": "#/components/schemas/sspcLongitude" }, { "$ref": "#/components/schemas/sspcLatitude" }, { "$ref": "#/components/schemas/sspgLongitude" }, { "$ref": "#/components/schemas/sspgLatitude" }, { "$ref": "#/components/schemas/sspdLongitude" }, { "$ref": "#/components/schemas/sspdLatitude" }, { "$ref": "#/components/schemas/ERA" }, { "$ref": "#/components/schemas/EQE" }, { "$ref": "#/components/schemas/EQO" }, { "$ref": "#/components/schemas/EQT" }, { "$ref": "#/components/schemas/LST" }, { "$ref": "#/components/schemas/lightTime" }, { "$ref": "#/components/schemas/TT-TDB" }, { "$ref": "#/components/schemas/TT-UT1" } ] } } } } }, "example": "EXAMPLEPOSITION" } } } }, "500": { "$ref": "#/components/responses/500" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/positions": { "post": { "summary": "Positions", "description": "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*.\n\nIf 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.\n\nA response, which contains the information about the requested position, is returned to the client encoded in *json* or *text* format. \n\nCapabilities : __URL__/v1/positions/capability", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "body", "observer", "reference", "date-set" ], "properties": { "body": { "description": "Observed body:\n - NAIF identification number of the observed body ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html))\n - identifier of an observed star : HIP number, WDS identifier.\n\nexample:\n - 4 for Mars\n - HIP-49669 for Regulus.", "oneOf": [ { "title": "NAIF identification number", "type": "integer", "minimum": 1, "example": 10 }, { "title": "Observed body:\n - NAIF identification number of the observed body ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html))\n - identifier of an observed star : HIP number, WDS identifier.\n\nexample:\n - 4 for Mars\n - HIP-49669 for Regulus.", "type": "string", "pattern": "^\\d{1,9}|HIP-\\d{1,6}$", "example": "HIP-11767" } ] }, "observer": { "description": "Location of the observer.\n\n Types of observers :\n - case of observer's location is at an Observatory, given by its IAU/MPC observatory code ([list](https://minorplanetcenter.net/iau/lists/ObsCodesF.html)). \n Example : \"observer\": \"obscode:007\" \n\n\n - case of observer's location is at the center of the celestial body given by its NAIF identification number ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html)) \n Example : \"observer\": 599 \n\n\n - 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). \n Example : \"observer\": [48.8534,2.3488,39] ", "oneOf": [ { "$ref": "#/components/schemas/observer_terrestrial_observatory_code" }, { "$ref": "#/components/schemas/observer_terrestrial_longitude_latitude_altitude" }, { "$ref": "#/components/schemas/observer_naif_identification" } ] }, "reference": { "description": "The axis or point used as the origin of the absolute or relative coordinates.\n\nAbsolute coordinates are computed if the reference is *origin*. Relative coordinates (e.g., tangential coordinates, elongation, ...) are computed if the reference is a celestial body.", "oneOf": [ { "$ref": "#/components/schemas/reference_string" }, { "$ref": "#/components/schemas/reference_naif_identification" } ] }, "date-set": { "description": "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*.", "type": "array", "items": { "oneOf": [ { "type": "number", "description": "Julian day, valid only if the item *calendar* is 'JD'", "example": 2459276.8486059606 }, { "type": "string", "title": "Calendar date", "description": "Gregorian or Julian calendar date, valid only if the parameter *calendar* is 'gregorian' or 'julian'. This calendar date is expressed using the notation YYYY-MM-DDTHH:MM:SS.SSS", "example": [ "2021-03-02T00:00:01.001", "2021-03-02T10:00:02.001" ] } ] }, "minItems": 1, "maxItems": 10000 }, "frame": { "description": "Reference frame. The coordinates are expressed in this frame.\n\n - 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.\n - GCRF : Geocentric Celestial Reference Frame; origin is the Earth's center of mass, axes are aligned with International Celestial Reference Frame.\n - 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.\n - MeanJ2000 : Mean Equinox/Mean Equator J2000; XY plane is the mean equator J2000 ; origin is the center of mass of the body.\n - EclipticJ2000 : Mean Equinox/Mean Ecliptic J2000; XY plane is the mean ecliptic J2000 ; origin is the center of mass of the body\n - 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\n - 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.\n - GTRF : the Geocentric Terrestrial Reference Frame, same as *BodyFixed* for the Earth.\n - 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.\n\nThe precession/nutation model IAU2000A and EOP series C04 are applied to the frames affected by the precession and nutation, such as TrueOfDate or BodyFixed.", "$ref": "#/components/schemas/frame" }, "timescale": { "description": "All dates and times of the request or response are expressed in this timescale.\n\nBefore 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.\n\nThe 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.", "$ref": "#/components/schemas/timescale" }, "calendar": { "description": "All dates and times of the request or response are expressed in this calendar.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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.\n- 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.", "$ref": "#/components/schemas/calendar" }, "theory": { "description": "Planetary and satellites theories used for the computations ([details](theories/))", "$ref": "#/components/schemas/theory", "style": "form", "explode": false }, "places": { "description": "Applied corrections to compute the positions of the celestial bodies and the observer.\n\n - 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.\n - 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.\n - 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.", "$ref": "#/components/schemas/places" }, "format": { "description": "The response format. The default response format is given by the header request Accept. If format is given, the header request Accept is ignored.", "$ref": "#/components/schemas/format" }, "coord-format": { "description": "Coordinates (angles, ...) of the response are expressed in decimal or in sexagesimal.\n\n - dec : decimal angles\n - sexa : sexagesimal angles.", "$ref": "#/components/schemas/coord-format" }, "distance-unit": { "description": "Distances of the response are expressed in Km or in AU.", "$ref": "#/components/schemas/distance-unit" }, "quantities": { "description": "Computed quantities of the observed body.\n\n - am : Relative air mass, ratio of absolute air masses at direction target relative to that at zenith. That quantity is stored in *airMass*.\n - 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*.\n - cart : absolute cartesian coordinates, expressed in *frame*. These coordinates are stored in *cartX*, *cartY* and *cartZ*.\n - radec : absolute equatorial coordinates (right ascension and declination), expressed in *frame*. These coordinates are stored in *RA* and *DEC*.\n - lonlat : absolute ecliptic coordinates (longitude and latitude), expressed in *frame*. These coordinates are stored in *longitude* and *latitude*.\n - hadec : absolute local hour angle and declination coordinates, expressed in the equatorial frame of the observer. These coordinates are stored in *HA* and *DEC*.\n - 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*.\n - dist : distance between the observed body and the observer. That coordinate is stored in *distance*.\n - 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*.\n - 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*.\n - deltaradec : relative equatorial coordinates (right ascension and declination) to the *reference*, expressed in *frame*. These coordinates are stored in *deltaRA* and *deltaDEC*.\n - el : elongation between the observed body and the *reference* seen by the observer. That coordinate is stored in *elongation*.\n - il : illuminated fraction of a body. The body is illuminated by the Sun. That quantity is stored in *illuminatedFraction*.\n - mag : observed apparent visual magnitude. That quantity is stored in *magnitude*.\n - pan : position angle of the north pole of the body. That quantity is stored in *PAn*.\n - par : parallactic angle of the body. That quantity is stored in *parallactic*.\n - phase : observed phase of the body, illuminated by the Sun. That quantity is stored in *phase*.\n - 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*.\n - 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*.\n - 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*.\n - sspa : Position angle of the subsolar point of the body from the Celestial North. That coordinate is stored in *sspa*.\n - 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*.\n - 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*.\n - 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*.\n - 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\u00b0, 90\u00b0, 180\u00b0 and 270\u00b0 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*.\n - lt : light-time from the observed body to the observer. That coordinate is stored in *lightTime*.\n - era : Earth Rotation Angle. That coordinate is stored in *ERA*.\n - eqe : Equation of the equinoxes. That coordinate is stored in *EQE*.\n - eqo : Equation of the origins. That coordinate is stored in *EQO*.\n - eqt : Equation of Time. That coordinate is stored in *EQT*.\n - lst : Local sidereal time of the observer. That coordinate is stored in *LST*.\n - TT-TDB : Difference between the time TT and TDB (=TT-TDB). That coordinate is stored in *TT-TDB*.\n - TT-UT1 : Difference between the time TT and UT1 (=TT-UT1). That coordinate is stored in *TT-UT1*.", "$ref": "#/components/schemas/quantities", "style": "form", "explode": false }, "theme": { "description": "Predefined styles of outputs and computed quantities.\n\n - default : default theme\n - dynastvo : theme for the dynastvo services.", "$ref": "#/components/schemas/theme" }, "extraprecision": { "description": "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.", "type": "integer", "minimum": 0, "maximum": 3, "example": 1, "default": 0 } } }, "examples": { "ApparentPositionsofVenus": { "summary": "Apparent positions of Venus from Paris Observatory", "value": { "body": 299, "observer": "obscode:007", "frame": "TrueOfDate", "timescale": "UTC", "reference": "origin", "places": "apparent", "quantities": [ "cart", "radec", "azel", "dist" ], "date-set": [ "2020-10-30T12:00:00.000", "2020-10-30T13:00:00.000", "2020-10-30T14:00:00.000" ] } }, "ApparentPositionsofVenusTxt": { "summary": "Apparent positions of Venus on text format", "value": { "body": 299, "observer": "obscode:007", "frame": "TrueOfDate", "timescale": "UTC", "reference": "origin", "places": "apparent", "quantities": [ "cart", "radec", "azel", "dist" ], "date-set": [ "2020-10-30T12:00:00.000", "2020-10-30T13:00:00.000", "2020-10-30T14:00:00.000" ], "format": "text" } }, "AstrometricPositionsOfIO": { "summary": "Astrometric positions of IO relative to Jupiter", "value": { "body": 501, "observer": [ 48.8534, 2.3488, 39 ], "frame": "MeanJ2000", "timescale": "UTC", "reference": 599, "places": "astrometric", "quantities": [ "tancart", "tanaz" ], "date-set": [ "2020-10-01T00:00:00.000", "2020-10-01T01:00:00.000" ] } }, "GeometricPositionsOfMoon": { "summary": "Geometric positions of the Moon with geocenter observer", "value": { "body": 301, "observer": 399, "frame": "BCRF", "timescale": "UTC", "reference": "origin", "places": "astrometric", "quantities": [ "cart" ], "date-set": [ "2021-09-20T00:00:00.000", "2021-09-20T01:00:00.000" ] } }, "PositionsOfJupiter": { "summary": "Positions of Jupiter with Paris observer", "value": { "body": 5, "observer": [ 48.8534, 2.3488, 39 ], "frame": "TrueOfDate", "timescale": "UTC", "reference": "origin", "places": "geometric", "quantities": [ "cart", "radec", "azel", "dist" ], "date-set": [ "2020-07-05T20:05:33.000", "2020-07-05T20:06:00.000", "2020-07-05T20:07:00.000" ] } }, "PositionsOfEarth": { "summary": "Positions of Earth with lunar observer", "value": { "body": 399, "observer": 301, "frame": "TrueOfDate", "timescale": "UTC", "reference": "origin", "places": "apparent", "quantities": [ "cart", "radec", "dist" ], "date-set": [ "2020-10-30T12:00:00", "2020-10-30T12:00:10.000" ] } } } } } }, "responses": { "200": { "description": "Positions", "content": { "application/json": { "schema": { "type": "object", "required": [ "response", "link", "request" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "request": { "type": "object", "description": "parameters of the current computation", "properties": {} }, "response": { "type": "object", "required": [ "data", "timescale", "calendar" ], "properties": { "calendar": { "description": "Calendar date of the computed data", "type": "string" }, "timescale": { "description": "Time scale of the computed data", "type": "string" }, "description": { "description": "Description of the fields of the object data", "type": "object", "properties": {} }, "unit": { "description": "Units of the fields of the object data", "type": "object", "properties": {} }, "data": { "type": "array", "items": { "anyOf": [ { "title": "date", "type": "string", "description": "Date ISO8601", "format": "date-time" }, { "$ref": "#/components/schemas/cartX" }, { "$ref": "#/components/schemas/cartY" }, { "$ref": "#/components/schemas/cartZ" }, { "$ref": "#/components/schemas/azimuth" }, { "$ref": "#/components/schemas/elevation" }, { "$ref": "#/components/schemas/airMass" }, { "$ref": "#/components/schemas/angDiameter" }, { "$ref": "#/components/schemas/magnitude" }, { "$ref": "#/components/schemas/phase" }, { "$ref": "#/components/schemas/longitude" }, { "$ref": "#/components/schemas/latitude" }, { "$ref": "#/components/schemas/Ls" }, { "$ref": "#/components/schemas/RA" }, { "$ref": "#/components/schemas/DEC" }, { "$ref": "#/components/schemas/LHA" }, { "$ref": "#/components/schemas/distance" }, { "$ref": "#/components/schemas/elongation" }, { "$ref": "#/components/schemas/X" }, { "$ref": "#/components/schemas/Y" }, { "$ref": "#/components/schemas/S" }, { "$ref": "#/components/schemas/positionAngle" }, { "$ref": "#/components/schemas/deltaRA" }, { "$ref": "#/components/schemas/deltaDEC" }, { "$ref": "#/components/schemas/sopcLongitude" }, { "$ref": "#/components/schemas/sopcLatitude" }, { "$ref": "#/components/schemas/sopgLongitude" }, { "$ref": "#/components/schemas/sopgLatitude" }, { "$ref": "#/components/schemas/sopdLongitude" }, { "$ref": "#/components/schemas/sopdLatitude" }, { "$ref": "#/components/schemas/sspcLongitude" }, { "$ref": "#/components/schemas/sspcLatitude" }, { "$ref": "#/components/schemas/sspgLongitude" }, { "$ref": "#/components/schemas/sspgLatitude" }, { "$ref": "#/components/schemas/sspdLongitude" }, { "$ref": "#/components/schemas/sspdLatitude" }, { "$ref": "#/components/schemas/ERA" }, { "$ref": "#/components/schemas/EQE" }, { "$ref": "#/components/schemas/EQO" }, { "$ref": "#/components/schemas/EQT" }, { "$ref": "#/components/schemas/LST" }, { "$ref": "#/components/schemas/lightTime" }, { "$ref": "#/components/schemas/TT-TDB" }, { "$ref": "#/components/schemas/TT-UT1" } ] } } } } }, "example": "EXAMPLEPOSITION" } } } }, "500": { "$ref": "#/components/responses/500" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/chart/sky": { "get": { "summary": "Sky chart", "description": "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.\n\nExamples:\n - Get the sky chart with the name of the planets, links and names of constellations, cardinal points, ecliptic plane, and local meridian, for an observer located at the observatory of Nice on April 15th, 2019 at 04h30 UTC :\n__URL__/v1/chart/sky?date=2019-04-15T04:30:00.0&observer=obscode:020&map-center=180,90&map-ecliptic-plane&map-constellation-link&map-constellation-label&map-cardinal-points&map-zenith&map-labels=en&map-solarsystembodies-label&map-time\n - Get the sky chart for an observer located at Lyon at the current time :\n__URL__/v1/chart/sky?observer=45.75,4.85&date=now&map-observer=name,coord&map-time\n - Get the sky chart for an observer located at Paris on July 5th, 2020 at 23h00 local time :\n__URL__/v1/chart/sky?date=2020-07-05T23:00:00.0×cale=Europe/Paris&observer=48.8534,2.3488,39&map-time\n\nCapabilities : __URL__/v1/chart/sky/capability", "parameters": [ { "in": "query", "name": "date", "description": "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": true, "schema": { "oneOf": [ { "title": "now", "description": "Current date-time of the request. The current time is truncated to a multiple of 5 minutes. The value of *timescale* is ignored and the displayed time is always expressed in the UTC timescale.", "type": "string", "enum": [ "now" ], "default": "now", "example": "now" }, { "type": "number", "description": "Julian day, valid only if the parameter *calendar* is 'JD'", "minimum": 0.0, "example": 2459276.8486059606 }, { "type": "string", "format": "date-time", "description": "Gregorian or Julian calendar date, valid only if the parameter *calendar* is 'gregorian' or 'julian'. This calendar date is expressed using the notation YYYY-MM-DDTHH:MM:SS.SSS", "example": "2021-01-01T00:00:01.000" } ] } }, { "in": "query", "name": "observer", "description": "Location of the observer on the Earth. A geocentric position (obscode:500) is not allowed if the parameter *map-coordinate-system* equals *azel*.", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/observer_terrestrial_observatory_code" }, { "$ref": "#/components/schemas/observer_terrestrial_longitude_latitude_altitude" } ], "example": [ 48, 150, 0 ], "default": "obscode:007" } }, { "in": "query", "name": "format", "description": "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.", "schema": { "type": "string", "enum": [ "image" ], "example": "image", "default": "image" } }, { "in": "query", "name": "image-style", "description": "The style of the exported image. The default style of the export image is *ssp*.", "schema": { "type": "string", "enum": [ "ssp", "sspdark", "newsletter", "astaf" ], "example": "ssp", "default": "ssp" } }, { "in": "query", "name": "timescale", "description": "All dates and times of the request or response are expressed in this timescale.\n\nThe supported timescales are :\n\n - UTC\n - UTC\u00b1hh:mm , where \u00b1hh:mm is the offset is the difference in hours and minutes from UTC.\n - name of a time zone. This name is one of the TZ database name ([list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)) e.g., Europe/Paris.\n - UT1", "required": true, "schema": { "$ref": "#/components/schemas/timescaleUTC" } }, { "in": "query", "name": "calendar", "description": "All dates and times of the request or response are expressed in this calendar.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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.\n- 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.", "schema": { "$ref": "#/components/schemas/calendar" } }, { "in": "query", "name": "image-format", "description": "The format of the exported image. The default format of the exported image is *png*.", "schema": { "type": "string", "enum": [ "png", "svg" ], "example": "png", "default": "png" } }, { "in": "query", "name": "image-size", "description": "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.", "schema": { "type": "array", "items": { "oneOf": [ { "description": "The width or height of the exported image in pixels.", "type": "integer", "minimum": 100, "maximum": 4000, "example": 1400, "default": 1400 }, { "type": "string", "enum": [ "auto" ], "example": "auto", "default": "auto" } ], "example": [ 1400, 1400 ] }, "minItems": 2, "maxItems": 2, "default": [ 1400, 1400 ] } }, { "in": "query", "name": "image-font-scale", "description": "Font scale factor applied to the labels.", "schema": { "type": "number", "minimum": 0.5, "maximum": 4, "example": 1, "default": 1 } }, { "in": "query", "name": "magnitude-limit", "description": "Show stars brighter than this magnitude.", "schema": { "type": "number", "minimum": 5, "maximum": 8, "example": 5, "default": 5 } }, { "in": "query", "name": "map-projection", "description": "The projection of the map. The default projection is the stereographic projection (ESRI:54026).\n - EPSG:9820 : Lambert Azimuthal Equal Area\n - EPSG:9825 : Pseudo Plate Carree\n - ESRI:54026 : Stereographic projection", "schema": { "type": "string", "enum": [ "EPSG:9820", "EPSG:9825", "ESRI:54026" ], "example": "ESRI:54026", "default": "ESRI:54026" } }, { "in": "query", "name": "map-center", "description": "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.", "schema": { "type": "array", "items": { "type": "number", "minimum": -180, "maximum": 180, "example": [ 180, 90 ] }, "minItems": 2, "maxItems": 2, "default": [ 180, 90 ] } }, { "in": "query", "name": "map-reference-point", "description": "Reference point for the projection.", "schema": { "oneOf": [ { "title": "automatic reference point", "description": "Set the value of reference point to a default value for the given projection.", "type": "string", "pattern": "^auto$", "enum": [ "auto" ], "default": "auto", "example": "auto" }, { "title": "user-defined reference point", "description": "The coordinates of the reference point 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.", "type": "array", "items": { "type": "integer", "description": "The coordinates of the reference point 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.", "minimum": -180, "maximum": 180, "minItems": 2, "maxItems": 2 }, "minItems": 2, "maxItems": 2, "example": [ 180, 90 ], "default": [ 180, 90 ] } ], "example": "auto", "default": "auto" } }, { "in": "query", "name": "map-coordinate-system", "description": "The celestial coordinate system specifing the center of the map. The default celestial coordinate system is the horizontal system (azel).\n - azel : horizontal system; Its fundamental plane is the horizon of the observer. The coordinates are azimuth and elevation.\n - equa : equatorial system; Its fundamental plane is the true equator plane. The coordinates are right ascension and declination.\n - ecli : ecliptic system; Its fundamental plane is the true ecliptic plane. The coordinates are longitude and latitude.", "schema": { "type": "string", "enum": [ "azel", "ecli", "equa" ], "example": "azel", "default": "azel" } }, { "in": "query", "name": "map-zoom", "description": "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.", "schema": { "type": "number", "minimum": 1, "maximum": 100, "example": 1, "default": 1 } }, { "in": "query", "name": "map-labels", "description": "Display the labels on the map.\n - en : english labels are displayed.\n - fr : french labels are displayed.", "schema": { "type": "string", "enum": [ "en", "fr" ], "example": "fr", "default": "fr" } }, { "in": "query", "name": "map-solarsystembodies-label", "description": "Show the name of the solar system bodies.", "schema": { "type": "boolean", "example": false, "default": false } }, { "in": "query", "name": "map-ecliptic-plane", "description": "Show the ecliptic plane as a solid line on the map with its name.", "schema": { "type": "boolean", "example": false, "default": false } }, { "in": "query", "name": "map-cardinal-points", "description": "Show the cardinal points, if the parameter *map-coordinate-system* equals to *azel*.", "schema": { "type": "boolean", "example": false, "default": false } }, { "in": "query", "name": "map-observer", "description": "Show the coordinates and/or location name of the observer.\n\n - coord : coordinates of the observer\n - 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.", "schema": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "coord", "name" ], "example": [ "coord", "name" ] }, "default": [] } }, { "in": "query", "name": "map-zenith", "description": "Show the local zenith, if the parameter *map-coordinate-system* equals to *azel*.", "schema": { "type": "boolean", "example": false, "default": false } }, { "in": "query", "name": "map-meridian", "description": "Show the local meridian as a solid line on the map with its name, if the parameter *map-coordinate-system* equals to *azel*..", "schema": { "type": "boolean", "example": false, "default": false } }, { "in": "query", "name": "map-time", "description": "Show the date, time and timescale of the sky chart.", "schema": { "type": "boolean", "example": false, "default": false } }, { "in": "query", "name": "map-constellation-link", "description": "Display the link of the constellations on the map.", "schema": { "type": "boolean", "example": false, "default": false } }, { "in": "query", "name": "map-constellation-label", "description": "Display the name of the constellations on the map.", "schema": { "type": "boolean", "example": false, "default": false } }, { "in": "query", "name": "map-constellation-boundary", "description": "Display the boundaries of the constellations on the map.", "schema": { "type": "boolean", "example": false, "default": false } }, { "in": "query", "name": "map-milkyway", "description": "Show the milky way.", "schema": { "type": "boolean", "example": false, "default": false } } ], "responses": { "200": { "description": "Sky chart", "content": { "image/png": { "schema": { "description": "Sky chart as png image", "type": "string" } } } }, "500": { "$ref": "#/components/responses/500" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/phenomena/occultations/{body}/{date}": { "get": { "summary": "Occultations", "description": "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.\n\nA 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.\n\nIf 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.\n\nExamples:\n- Get all occultations of Mars on the year 2018 : __URL__/v1/phenomena/occultations/499/2018\n- Get the data of the occultation of Mars by the Moon on April 17, 2021 : __URL__/v1/phenomena/occultations/499/2021-04-17 \n- Get the map of the occultation of Mars by the Moon on April 17, 2021 in svg image : __URL__/v1/phenomena/occultations/499/2021-04-17?format=image\n- Get the map of the occultation of the star \u03b2 Scorpio by the Moon on January 15, 2020 in svg image : __URL__/v1/phenomena/occultations/HIP-57380/2020-01-15?occulting=301&format=image&map-theme=country-medium", "parameters": [ { "in": "path", "name": "body", "description": "Occulted body:\n - NAIF identification number of the occulted body\n - identifier of an occulted star : HIP number, WDS identifier\n. The NAIF identification number should be the center of mass of the planet, and not its barycenter of the planet and satellites.\n\nexample:\n - 499 for Mars\n - 599 for Jupiter\n - HIP-49669 for Regulus.", "required": true, "schema": { "type": "string", "pattern": "^\\d{3,9}|HIP-\\d{1,6}$", "example": "499" } }, { "in": "path", "name": "date", "description": "Filter by year or day. \n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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.\n\n", "required": true, "schema": { "oneOf": [ { "title": "Year", "description": "Year. Only the occultations occuring this given year are returned.\n\nThe optional calendar specifies the calendar of this year. If the calendar is not given, then the year is assumed to be expressed in the (proleptic) gregorian calendar.", "type": "string", "pattern": "^(gregorian,|julian,)?-?\\d{1,4}$", "example": "2020" }, { "title": "Calendar date", "description": "Calendar date YYYY-MM-DD. Only the occultation of around this day (previous or next day) is returned.\n\nThe optional calendar specifies the calendar of this date. If the calendar is not given, then date is assumed to be expressed in the (proleptic) gregorian calendar.", "type": "string", "pattern": "^(gregorian,|julian,)?-?\\d{4}-(0?[1-9]|1[0-2])-(0?[1-9]|[12]\\d|3[01])$", "example": "2020-01-10" } ] }, "example": "__CURRENTYEAR__", "style": "simple" }, { "in": "query", "name": "nbd", "description": "Number of years to compute. This parameter is ignored if the parameter is not a year", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "example": 1, "default": 1 } }, { "in": "query", "name": "occulting", "description": "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", "schema": { "type": "string", "pattern": "^\\d{3,8}$", "example": "301", "default": "301" } }, { "in": "query", "name": "observer", "description": "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.", "schema": { "oneOf": [ { "$ref": "#/components/schemas/observer_geocenter" }, { "$ref": "#/components/schemas/observer_terrestrial_observatory_code" }, { "$ref": "#/components/schemas/observer_terrestrial_longitude_latitude_altitude" } ] } }, { "in": "query", "name": "format", "description": "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.", "schema": { "type": "string", "enum": [ "json", "image", "video" ], "example": "json", "default": "json" } }, { "in": "query", "name": "image-format", "description": "The format of the exported image. The default format of the exported image is *svg*.", "schema": { "type": "string", "enum": [ "svg", "eps", "pdf" ], "example": "svg", "default": "svg" } }, { "in": "query", "name": "video-format", "description": "The format of the exported video. The default format of the exported video is *mp4*.", "schema": { "type": "string", "enum": [ "hls", "mp4", "webm" ], "example": "mp4", "default": "mp4" } }, { "in": "query", "name": "video-definition", "description": "The definition of the exported video. The default definition of the exported video is *HD*.\n\n - custom : the resolution is given by the parameter *image-size*.\n - SD : the number of lines of video is set to 576. The width of the video is adjusted in order to respect the projection.\n - HD : the number of lines of video is set to 720. The width of the video is adjusted in order to respect the projection.\n - FHD : the number of lines of video is set to 1080. The width of the video is adjusted in order to respect the projection.", "schema": { "type": "string", "enum": [ "custom", "SD", "HD", "FHD" ], "example": "HD", "default": "HD" } }, { "in": "query", "name": "image-size", "description": "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.", "schema": { "type": "array", "items": { "oneOf": [ { "description": "The width or height of the exported image in pixels.", "type": "integer", "minimum": 100, "maximum": 4000, "example": 800, "default": 800 }, { "type": "string", "enum": [ "auto" ], "example": "auto", "default": "auto" } ], "example": [ 800, 600 ] }, "minItems": 2, "maxItems": 2, "default": [ 800, 600 ] } }, { "in": "query", "name": "image-style", "description": "The style of the exported image. The default style of the export image is *ssp*.", "schema": { "type": "string", "enum": [ "ssp", "newsletter" ], "example": "ssp", "default": "ssp" } }, { "in": "query", "name": "map-projection", "description": "The projection of the map. The default projection is the Mercator conformal projection (EPSG:3395).\n - EPSG:3395 : Mercator conformal projection\n - EPSG:3857 : Web-Mercator or pseudo-Mercator projection\n - EPSG:9820 : Lambert Azimuthal Equal Area\n - EPSG:9825 : Pseudo Plate Carree\n - EPSG:9840 : Orthographic projection\n - ESRI:54026 : Stereographic projection", "schema": { "type": "string", "enum": [ "EPSG:3395", "EPSG:3857", "EPSG:9840", "EPSG:9820", "EPSG:9825", "ESRI:54026" ], "example": "EPSG:3395", "default": "EPSG:3395" } }, { "in": "query", "name": "map-center", "description": "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.", "schema": { "type": "array", "items": { "type": "number", "minimum": -180, "maximum": 180, "example": [ 0, 0 ] }, "minItems": 2, "maxItems": 2, "default": [ 0, 0 ] } }, { "in": "query", "name": "map-theme", "description": "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'.\n - land-small : show the lands and major islands. Suitable for schematic map of the occultation\n - land-medium : show the lands and major islands. Suitable for detailed map of the occultation\n - country-small : show the country boundaries. Suitable for schematic map of the occultation\n - country-medium : show the country boundaries. Suitable for detailed map of the occultation", "schema": { "type": "string", "enum": [ "land-small", "land-medium", "country-small", "country-medium" ], "example": "land-small", "default": "land-small" } }, { "in": "query", "name": "map-zoom", "description": "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.", "schema": { "type": "number", "minimum": 1, "maximum": 20, "example": 1, "default": 1 } }, { "in": "query", "name": "map-labels", "description": "Display the label of the lines of the events on the map.\n - none : no label is displayed.\n - en : english labels (P1, U1, U2, U3, U4, P4) are displayed.\n - fr : french labels (P1, O1, T1, T2, O2, P2) are displayed.", "schema": { "type": "string", "enum": [ "none", "en", "fr" ], "example": "none", "default": "none" } } ], "responses": { "200": { "description": "Occultations", "content": { "application/json": { "schema": { "description": "Data of the occulations", "type": "object", "required": [ "response", "link", "request" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "request": { "type": "object", "description": "parameters of the current computation", "properties": {} }, "response": { "type": "object", "required": [ "calendar", "data", "timescale" ], "properties": { "calendar": { "description": "All dates and times of the request or response are expressed in this calendar", "type": "string" }, "timescale": { "description": "Time scale of the computed data", "type": "string" }, "description": { "description": "Description of the fields of the object data", "type": "object", "properties": {} }, "unit": { "description": "Units of the fields of the object data", "type": "object", "properties": {} }, "data": { "description": "Array of the occultations", "type": "array", "items": { "type": "object", "required": [ "type", "duration", "events", "calendarDate", "physicalData", "link", "bodies" ], "properties": { "type": { "description": "Type of the occultation.\n\n For the general circumstances :\n - NonCentralPartialOccultation : partial occultation\n - NonCentralTotalOccultation : non central total occultation\n - CentralTotalOccultation : central total occultation\n - NonCentralAnnularOccultation : non central transit (or annular occultation)\n - CentralAnnularOccultation : central transit (or annular occultation)\n\n For the local circumstances :\n - ObserverPartialOccultation : partial occultation\n - ObserverTotalOccultation : total occultation\n - ObserverAnnularOccultation : transit (or annular occultation)\n", "type": "string", "enum": [ "NonCentralPartialOccultation", "NonCentralTotalOccultation", "NonCentralAnnularOccultation", "CentralTotalOccultation", "CentralAnnularOccultation", "ObserverPartialOccultation", "ObserverTotalOccultation", "ObserverAnnularOccultation" ] }, "calendarDate": { "description": "Calendar date of the occultation, truncated to the day (YYYY-MM-DD). The calendar of this date depends on the response property *{calendar}*.", "type": "string" }, "duration": { "description": "Duration of each phase of the occultation", "type": "object", "required": [ "grazing", "total" ], "properties": { "grazing": { "description": "Interval in HH:MM:SS between the beginning and the end of the grazing phase", "type": "string", "nullable": true }, "total": { "description": "Interval in HH:MM:SS between the beginning and the end of the total phase", "type": "string", "nullable": true } } }, "bodies": { "description": "Physical data of the bodies", "type": "object", "required": [ "occulted", "occulting" ], "properties": { "occulted": { "description": "identification of the occulted body", "type": "object", "required": [ "body", "type" ], "properties": { "body": { "description": "Identification number or string of the occulted body", "type": "string" }, "name": { "description": "Common name of the occulted body.", "type": "string" }, "type": { "description": "Type of the occulted body.", "type": "string", "enum": [ "Star", "SolarSystemBody" ] } } }, "occulting": { "description": "Physical data of the occulting body", "type": "object", "required": [ "body" ], "properties": { "body": { "description": "Identification number or string of the occulting body", "type": "string" } } } } }, "physicalData": { "description": "Physical data of the bodies", "type": "object", "required": [ "occultedBody", "OccultingBody", "Earth" ], "properties": { "occultedBody": { "description": "Physical data of the occulted body", "type": "object", "required": [ "radius" ], "properties": { "radius": { "description": "Equatorial radius of the occulted body", "type": "number" } } }, "occultingBody": { "description": "Physical data of the occulting body", "type": "object", "required": [ "radius" ], "properties": { "radius": { "description": "Equatorial radius of the occulting body", "type": "number" } } }, "Earth": { "description": "Physical data of the Earth", "type": "object", "required": [ "radius", "inverseFlattening" ], "properties": { "radius": { "description": "Equatorial radius of the Earth", "type": "number" }, "inverseFlattening": { "description": "Inverse of the flattening of the Earth's ellipsoid", "type": "number" } } } } }, "events": { "description": "Different instants of the occultations", "type": "object", "required": [ "greatest", "P1", "P4" ], "properties": { "greatest": { "title": "Instant of the greatest occultation and the position of the occulted and occulting bodies and on the Earth", "nullable": true, "$ref": "#/components/schemas/occultation_contact" }, "P1": { "description": "Instant of first exterior tangency of the Penumbra with the surface of the Earth", "nullable": true, "$ref": "#/components/schemas/occultation_contact" }, "P2": { "description": "Instant of first interior tangency of the Penumbra with the surface of the Earth", "nullable": true, "$ref": "#/components/schemas/occultation_contact" }, "U1": { "description": "Instant of first exterior tangency of umbra with the surface of the Earth.", "nullable": true, "$ref": "#/components/schemas/occultation_contact" }, "C1": { "description": "Instant of first contact of the umbral axis with the surface of the Earth.", "nullable": true, "$ref": "#/components/schemas/occultation_contact" }, "U2": { "description": "Instant of first interior tangency of umbra with the surface of the Earth.", "nullable": true, "$ref": "#/components/schemas/occultation_contact" }, "U3": { "description": "Instant of last interior tangency of umbra with the surface of the Earth.", "nullable": true, "$ref": "#/components/schemas/occultation_contact" }, "C2": { "description": "Instant of last contact of the umbral axis with the surface of the Earth.", "nullable": true, "$ref": "#/components/schemas/occultation_contact" }, "U4": { "description": "Instant of last exterior tangency of umbra with the surface of the Earth.", "nullable": true, "$ref": "#/components/schemas/occultation_contact" }, "P3": { "description": "Instant of last interior tangency of the Penumbra with the surface of the Earth", "nullable": true, "$ref": "#/components/schemas/occultation_contact" }, "P4": { "description": "Instant of last exterior tangency of the Penumbra with the surface of the Earth", "nullable": true, "$ref": "#/components/schemas/occultation_contact" } } }, "link": { "type": "object", "required": [ "self", "image" ], "properties": { "self": { "description": "uri of the data of the occultation", "type": "string", "format": "uri" }, "image": { "description": "uri of the image of the occultation", "type": "string", "format": "uri" }, "video": { "description": "uri of the video of the occultation", "type": "string", "format": "uri" } } }, "visibilityLines": { "type": "object", "description": "GeoJson lines of the visibility of the occultation" }, "visibilityPaths": { "type": "object", "description": "GeoJson lines of the grazing and total paths of the occultation" } } } } } } }, "example": "EXAMPLEOCCULTATION" } }, "application/postscript": { "schema": { "description": "Map of the occultation as postscript image", "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "description": "Map of the occultation as pdf image", "type": "string", "format": "binary" } }, "image/svg+xml": { "schema": { "description": "Map of the occultation as svg image", "type": "string" } }, "video/mp4": { "schema": { "description": "Animation of the occultation as mp4 video", "type": "string", "format": "binary" } }, "video/webm": { "schema": { "description": "Animation of the occultation as webm video", "type": "string", "format": "binary" } } } }, "202": { "description": "The request has been accepted for processing, but the processing has not been completed.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "response" ], "properties": { "response": { "type": "object", "required": [ "estimatedDelay", "workProgress" ], "properties": { "estimatedDelay": { "description": "Estimation of the delay, expressed in seconds, to obtain the result of the processing", "type": "number" }, "workProgress": { "description": "Current amount of work that has been completed for this processing. The value 0 means that no work has been done and a value of 100 means that the processing is almost finished", "type": "number", "minimum": 0, "maximum": 100 } } } } } } } }, "206": { "description": "Partial content of the movie of the occultations", "content": { "video/mp4": { "schema": { "description": "Animation of the occultation as mp4 video", "type": "string", "format": "binary" } }, "video/webm": { "schema": { "description": "Animation of the occultation as webm video", "type": "string", "format": "binary" } } } }, "500": { "$ref": "#/components/responses/500" }, "416": { "$ref": "#/components/responses/416" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/phenomena/elongations": { "get": { "summary": "Extreme elongations", "description": "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.\n\nA response, which contains the information about all phenomena, is returned to the client encoded in json format.\n\nExamples:\n - Get all greatest elongations of Venus relative to the Sun, seen from the geocenter, from the year 2022 to 2023: __URL__/v1/phenomena/elongations?date=2022-01-01T00:00:00&nbd=730&body=2&reference=10&observer=399&extrema=max\n - Get all minimal elongations of Mars relative to the Moon, seen from the geocenter, from the year 2022 to 2024: __URL__/v1/phenomena/elongations?date=2022-01-01T00:00:00&nbd=1095&body=4&reference=301&observer=399&extrema=min&coord-format=sexa\n - Get all maximal elongations of Io relative to the Jupiter, seen from the geocenter, from January 1st, 2022 to January 15st 2022: __URL__/v1/phenomena/elongations?date=2022-01-01T00:00:00&nbd=15&body=501&reference=599&observer=399&extrema=max&coord-format=sexa", "parameters": [ { "in": "query", "name": "body", "description": "Observed body:\n - NAIF identification number of the observed body ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html))\n - identifier of an observed star : HIP number, WDS identifier.\n\nexample:\n - 4 for Mars\n - HIP-49669 for Regulus.", "required": true, "schema": { "type": "string", "pattern": "^\\d{1,9}|HIP-\\d{1,6}$", "example": "1", "default": "1" } }, { "in": "query", "name": "reference", "required": true, "description": "NAIF identification number of the reference point ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html))", "schema": { "type": "integer", "example": 10, "default": 10 } }, { "in": "query", "name": "observer", "required": true, "description": "Location of the observer.", "schema": { "oneOf": [ { "$ref": "#/components/schemas/observer_terrestrial_observatory_code" }, { "$ref": "#/components/schemas/observer_terrestrial_longitude_latitude_altitude" }, { "$ref": "#/components/schemas/observer_naif_identification" } ] } }, { "in": "query", "name": "date", "required": true, "description": "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*.", "schema": { "oneOf": [ { "type": "number", "description": "Julian day, valid only if the parameter *calendar* is 'JD'", "minimum": 0.0, "example": 2459276.8486059606 }, { "type": "string", "format": "date-time", "description": "Gregorian or Julian calendar date, valid only if the parameter *calendar* is 'gregorian' or 'julian'. This calendar date is expressed using the notation YYYY-MM-DDTHH:MM:SS.SSS", "example": "2021-01-01T00:00:01.000" } ] } }, { "in": "query", "name": "calendar", "description": "All dates and times of the request or response are expressed in this calendar.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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.\n - 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.", "schema": { "$ref": "#/components/schemas/calendar" } }, { "in": "query", "name": "nbd", "description": "Length of the timespan, expressed in days", "schema": { "type": "integer", "minimum": 14, "maximum": 36525, "example": 365, "default": 365 } }, { "in": "query", "name": "coord-format", "description": "Coordinates (angles, ...) of the response are expressed in decimal or in sexagesimal.\n\n - dec : decimal angles\n - sexa : sexagesimal angles.", "schema": { "$ref": "#/components/schemas/coord-format" } }, { "in": "query", "name": "extrema", "required": true, "description": "Minimum or maximum elongations", "schema": { "type": "string", "enum": [ "min", "max" ], "default": "min", "example": "min" } }, { "in": "query", "name": "timescale", "description": "All dates and times of the request or response are expressed in this timescale.\n\nBefore 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.\n\nThe 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.", "schema": { "$ref": "#/components/schemas/timescale" } } ], "responses": { "200": { "description": "Minimal elongations or greastest elongations between two bodies", "content": { "application/json": { "schema": { "description": "Minimal elongations or greastest elongations between two bodies", "type": "object", "required": [ "response", "link", "request" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "request": { "type": "object", "description": "parameters of the current computation", "properties": {} }, "response": { "type": "object", "required": [ "data", "unit" ], "properties": { "description": { "description": "Description of the fields of the object data", "type": "object", "properties": {} }, "unit": { "description": "Units of the field distance", "type": "object", "properties": {} }, "data": { "description": "Array of minimum and maximum elongation between the two bodies", "type": "array", "items": { "type": "object", "required": [ "date", "distance", "phenomena" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "distance": { "description": "Angle between the two bodies", "type": "number" }, "phenomena": { "description": "Event type", "type": "string", "uniqueItems": true, "enum": [ "MinimalElongation", "MaximalElongation" ] } } } } } } }, "example": "EXAMPLEELONGATION" } } } }, "500": { "$ref": "#/components/responses/500" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/phenomena/distances": { "get": { "summary": "Extreme distances", "description": "Get all minimum and maximum geometric distances between two bodies over a given timespan. No light-time, aberration or refraction correction is applied.\n The instants of the events are given in the timescale UTC by default.\n\nA response, which contains the information about all phenomena, is returned to the client encoded in json format.\n\nExamples: \n- Get all the perigees and apogees of the Moon for January 2022 : __URL__/v1/phenomena/distances?date=2022-01-01T00:00:00&nbd=31&bodies=399,301", "parameters": [ { "in": "query", "name": "bodies", "description": "NAIF identification number of the two bodies [list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html)", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/observer_terrestrial_observatory_code" }, { "$ref": "#/components/schemas/observer_terrestrial_longitude_latitude_altitude" }, { "$ref": "#/components/schemas/observer_naif_identification" } ] } }, { "in": "query", "name": "date", "required": true, "description": "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*.", "schema": { "oneOf": [ { "type": "number", "description": "Julian day, valid only if the parameter *calendar* is 'JD'", "minimum": 0.0, "example": 2459276.8486059606 }, { "type": "string", "format": "date-time", "description": "Gregorian or Julian calendar date, valid only if the parameter *calendar* is 'gregorian' or 'julian'. This calendar date is expressed using the notation YYYY-MM-DDTHH:MM:SS.SSS", "example": "2021-01-01T00:00:01.000" } ] } }, { "in": "query", "name": "calendar", "required": true, "description": "All dates and times of the request or response are expressed in this calendar.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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.\n - 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.", "schema": { "$ref": "#/components/schemas/calendar" } }, { "in": "query", "name": "nbd", "description": "Length of the timespan, expressed in days", "schema": { "type": "integer", "minimum": 14, "maximum": 36525, "example": 365, "default": 365 } }, { "in": "query", "name": "distance-unit", "description": "Distances of the response are expressed in Km or in AU.", "schema": { "$ref": "#/components/schemas/distance-unit" } }, { "in": "query", "name": "timescale", "description": "All dates and times of the request or response are expressed in this timescale.\n\nBefore 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.\n\nThe 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.", "schema": { "$ref": "#/components/schemas/timescale" } } ], "responses": { "200": { "description": "Extreme distances between the two bodies", "content": { "application/json": { "schema": { "description": "Extreme distances between the two bodies", "type": "object", "required": [ "response", "link", "request" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "request": { "type": "object", "description": "parameters of the current computation", "properties": {} }, "response": { "type": "object", "required": [ "data", "unit" ], "properties": { "description": { "description": "Description of the fields of the object data", "type": "object", "properties": {} }, "unit": { "description": "Units of the field distance", "type": "object", "properties": {} }, "data": { "description": "Array of minimum and maximum distances between the two bodies", "type": "array", "items": { "type": "object", "required": [ "date", "distance", "phenomena" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "distance": { "description": "Distance between the two bodies", "type": "number" }, "phenomena": { "description": "Event type", "type": "string", "uniqueItems": true, "enum": [ "MinimalDistance", "MaximalDistance" ] } } } } } } }, "example": "EXAMPLEDISTANCE" } } } }, "500": { "$ref": "#/components/responses/500" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/phenomena/oppositions/{body}": { "get": { "summary": "Oppositions", "description": "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.\n The instants of the events are given in the timescale UTC by default.\n\nA response, which contains the information about all phenomena, is returned to the client encoded in json format.\n\nExamples: \n- Get all the oppositions of Mars between January 2022 and December 2023: __URL__/v1/phenomena/oppositions/4?date=2022-01-01T00:00:00&nbd=730", "parameters": [ { "in": "path", "required": true, "name": "body", "description": "NAIF identification number of the body ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html))", "schema": { "type": "integer", "example": 5, "minimum": 4 } }, { "in": "query", "required": true, "name": "date", "description": "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*.", "schema": { "oneOf": [ { "type": "number", "description": "Julian day, valid only if the parameter *calendar* is 'JD'", "minimum": 0.0, "example": 2459276.8486059606 }, { "type": "string", "format": "date-time", "description": "Gregorian or Julian calendar date, valid only if the parameter *calendar* is 'gregorian' or 'julian'. This calendar date is expressed using the notation YYYY-MM-DDTHH:MM:SS.SSS", "example": "2021-01-01T00:00:01.000" } ] } }, { "in": "query", "required": true, "name": "timescale", "description": "All dates and times of the request or response are expressed in this timescale.\n\nThe supported timescales are \n - UTC\n - UTC\u00b1hh:mm , where \u00b1hh:mm is the difference in hours and minutes from UTC. The plus sign math symbol, in the character \u00b1, must be encoded using the characters %2B.\n - UT1\n\nBefore 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.\n\nThe 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.", "schema": { "$ref": "#/components/schemas/timescaleUTCUT1" } }, { "in": "query", "name": "calendar", "description": "All dates and times of the request or response are expressed in this calendar.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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": true, "schema": { "$ref": "#/components/schemas/calendarJulianOrGregorian" } }, { "in": "query", "required": true, "name": "nbd", "description": "The number of days to compute", "schema": { "type": "integer", "minimum": 1, "maximum": 36525, "example": 3652, "default": 3652 } } ], "responses": { "200": { "description": "Oppositions of a body for a geocentric observer relative to the Sun", "content": { "application/json": { "schema": { "type": "object", "required": [ "response", "link", "request" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "request": { "type": "object", "description": "parameters of the current computation", "properties": {} }, "response": { "type": "object", "required": [ "data", "unit" ], "properties": { "description": { "description": "Description of the fields of the object data", "type": "object", "properties": {} }, "data": { "description": "Array of the oppositions", "type": "array", "items": { "type": "object", "required": [ "date", "distance" ], "properties": { "date": { "description": "Instant of the event", "$ref": "#/components/schemas/date" }, "distance": { "description": "Astrometric distance between the body and the geocenter at the instant of the event, expressed in astronomical unit", "type": "number" } } } } } } }, "example": "EXAMPLEOPPOSITION" } } } }, "500": { "$ref": "#/components/responses/500" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/upcoming/occultations": { "get": { "summary": "Upcoming occultations", "description": "Get the upcoming occultations. The following upcoming occultations are computed :\n- Planets occulted by the Moon.\n- Stars, brigther than the visual apparent magnitude 3, occulted by the Moon\n\nExamples:\n __URL__/v1/upcoming/occultations", "parameters": [], "responses": { "200": { "description": "Upcoming occultations", "content": { "application/json": { "schema": { "type": "object", "required": [ "response", "link" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "response": { "type": "object", "required": [ "calendar", "data", "timescale" ], "properties": { "calendar": { "description": "All dates and times of the request or response are expressed in this calendar", "type": "string" }, "timescale": { "description": "Time scale of the computed data", "type": "string" }, "description": { "description": "Description of the fields of the object data", "type": "object", "properties": {} }, "unit": { "description": "Units of the fields of the object data", "type": "object", "properties": {} }, "data": { "description": "Array of the occultations", "type": "array", "items": { "type": "object", "required": [ "date", "duration", "bodiesElongation", "occulted", "occulting", "link" ], "properties": { "date": { "description": "Instant of the beginning of the occultations, visible on the Earth. Gregorian date or Gregorian proleptic date (ISO-8601 compliant date), valid only if the item response 'calendar' has the value 'Gregorian'", "type": "string" }, "duration": { "description": "Duration fo the occultation", "type": "number" }, "occulted": { "description": "Data of the occulted body", "type": "object", "required": [ "body", "type" ], "properties": { "body": { "description": "Identification number or string of the occulted body", "type": "string" }, "magnitude": { "description": "Visual apparent magitude of the occulted body", "type": "number" }, "name": { "description": "Common name of the occulted body.", "type": "string" }, "type": { "description": "Type of the occulted body.", "type": "string", "enum": [ "Star", "SolarSystemBody" ] } } }, "occulting": { "description": "Data of the occulting body", "type": "object", "required": [ "body", "solarElongation", "illuminatedFraction" ], "properties": { "body": { "description": "Identification number or string of the occulting body", "type": "string" }, "magnitude": { "description": "Visual apparent magitude of the occulting body", "type": "number" }, "solarElongation": { "description": "Elongation between the Sun and the occulting body at the instant of the greatest event", "$ref": "#/components/schemas/angle" }, "illuminatedFraction": { "description": "Illuminated fraction of the occulting body by the Sun at the instant of the greatest event", "type": "number" } } }, "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the data of the occultation", "type": "string", "format": "uri" } } } } } } } } }, "example": "EXAMPLEUPCOMINGOCCULTATION" } } } }, "500": { "$ref": "#/components/responses/500" }, "400": { "$ref": "#/components/responses/400_get" } } } }, "/v1/residuals": { "post": { "summary": "Residuals", "description": "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*.\n\nA 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.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "body", "observer", "date-set", "observations", "coord" ], "properties": { "body": { "description": "NAIF identification number of the observed body ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html))", "type": "integer", "minimum": 1, "example": 10 }, "observer": { "description": "Location of the observer.\n\n Types of observers :\n - case of observer's location is at an Observatory, given by its IAU/MPC observatory code ([list](https://minorplanetcenter.net/iau/lists/ObsCodesF.html)). \n Example : \"observer\": \"obscode:007\" \n\n\n - case of observer's location is at the center of the celestial body given by its NAIF identification number ([list](https://calceph.imcce.fr/docs/latest/html/c/calceph.naifid.html)) \n Example : \"observer\": 599 \n\n\n - 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). \n Example : \"observer\": [48.8534,2.3488,39] ", "oneOf": [ { "$ref": "#/components/schemas/observer_terrestrial_observatory_code" }, { "$ref": "#/components/schemas/observer_terrestrial_longitude_latitude_altitude" }, { "$ref": "#/components/schemas/observer_naif_identification" } ] }, "date-set": { "description": "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*.", "type": "array", "items": { "oneOf": [ { "type": "number", "description": "Julian day, valid only if the item *calendar* is 'JD'", "example": 2459276.8486059606 }, { "type": "string", "title": "Calendar date", "description": "Gregorian or Julian calendar date, valid only if the parameter *calendar* is 'gregorian' or 'julian'. This calendar date is expressed using the notation YYYY-MM-DDTHH:MM:SS.SSS", "example": [ "2021-03-02T00:00:01.001", "2021-03-02T10:00:02.001" ] } ] }, "minItems": 1, "maxItems": 10000 }, "frame": { "description": "Reference frame. The coordinates are expressed in this frame.\n\n - 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.\n - GCRF : Geocentric Celestial Reference Frame; origin is the Earth's center of mass, axes are aligned with International Celestial Reference Frame.\n - 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.\n - MeanJ2000 : Mean Equinox/Mean Equator J2000; XY plane is the mean equator J2000 ; origin is the center of mass of the body.\n - EclipticJ2000 : Mean Equinox/Mean Ecliptic J2000; XY plane is the mean ecliptic J2000 ; origin is the center of mass of the body\n - 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\n - 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.\n - GTRF : the Geocentric Terrestrial Reference Frame, same as *BodyFixed* for the Earth.\n - 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.\n\nThe precession/nutation model IAU2000A and EOP series C04 are applied to the frames affected by the precession and nutation, such as TrueOfDate or BodyFixed.", "$ref": "#/components/schemas/frame" }, "timescale": { "description": "All dates and times of the request or response are expressed in this timescale.\n\nBefore 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.\n\nThe 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.", "$ref": "#/components/schemas/timescale" }, "calendar": { "description": "All dates and times of the request or response are expressed in this calendar.\n\nThe supported calendars are :\n- gregorian : Gregorian calendar. In early eras, the adopted calendar is the *proleptic Gregorian calendar*. It complies with the ISO 8601 standard.\n- 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.\n - 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.", "$ref": "#/components/schemas/calendar" }, "observations": { "description": "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**", "type": "array", "items": { "type": "array", "items": { "type": "string", "pattern": "^(([+-]?([0-9]+([.][0-9]*)?|[.][0-9]+))|(([+-]?\\s*?\\d+)\\s(\\d+)\\s([0-9]+\\.?[0-9]*))|(([+-]?\\s*?\\d+)\\s([0-9]+\\.?[0-9]*)))$", "example": "21.3" } }, "minItems": 1, "maxItems": 10000 }, "coord": { "description": "Type of the observations :\n - 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].\n - 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", "type": "string", "enum": [ "RA/DEC-dec", "RA/DEC-sexa" ] }, "theory": { "description": "Planetary and satellites theories used for the computations ([details](theories/))", "$ref": "#/components/schemas/theory", "style": "form", "explode": false } } }, "examples": { "ResidualJupiter": { "summary": "O-C Jupiter", "value": { "body": 5, "calendar": "gregorian", "date-set": [ "2022-01-01T00:00:00.000", "2022-02-01T00:00:00.000" ], "observer": 399, "timescale": "UTC", "observations": [ [ "22.1789", "-12.316" ], [ "22.60", "-9.876" ] ], "theory": [ "INPOP19A", "NOE-4-2020", "NOE-5-2021", "NOE-6-2018", "NOE-7-2013", "SAI-5-2021", "SAI-6-2021", "SAI-7-2021", "SAI-8-2015", "SAI-8-2021" ], "coord": "RA/DEC-dec" } } } } } }, "responses": { "200": { "description": "Residuals (O-C)", "content": { "application/json": { "schema": { "type": "object", "required": [ "response", "link", "request" ], "properties": { "link": { "type": "object", "required": [ "self" ], "properties": { "self": { "description": "uri of the current computation", "type": "string", "format": "uri" } } }, "request": { "type": "object", "description": "parameters of the current computation", "properties": {} }, "response": { "type": "object", "required": [ "data", "timescale", "calendar", "statistics" ], "properties": { "calendar": { "description": "Calendar date of the computed data", "type": "string" }, "timescale": { "description": "Time scale of the computed data", "type": "string" }, "description": { "description": "Description of the fields of the object data", "type": "object", "properties": {} }, "unit": { "description": "Units of the fields of the object data", "type": "object", "properties": {} }, "data": { "description": "array of the residuals", "type": "array", "items": { "type": "object", "required": [ "date", "residual" ], "properties": { "date": { "description": "date of the observation", "$ref": "#/components/schemas/date" }, "deltaRA": { "description": "difference between the observation and the computation (O-C) in right ascension (\u0394\u03b1), expressed in arcseconds", "$ref": "#/components/schemas/angle" }, "deltaRAcosDEC": { "description": "difference between the observation and the computation (O-C) in right ascension times the cosine of the declination (\u0394\u03b1cos(\u03b4)), expressed in arcseconds", "$ref": "#/components/schemas/angle" }, "deltaDEC": { "description": "difference between the observation and the computation (O-C) in declination (\u0394\u03b4), expressed in arcseconds", "$ref": "#/components/schemas/angle" } } } }, "statistics": { "description": "Statistics about the differences", "type": "object", "properties": { "correlationCoefficientPearson": { "description": "Pearson correlation coefficient (PCC)", "type": "object", "properties": { "deltaRA-deltaDEC": { "description": "Pearson correlation coefficient (PCC) between the differences in right ascension and the differences in declination", "type": "number" }, "deltaRAcosDEC-deltaDEC": { "description": "Pearson correlation coefficient (PCC) between the differences in right ascension times the cosine of the declination and the differences in declination", "type": "number" } } }, "covariance": { "description": "Covariance between the differences in right ascension and the differences in declination", "type": "object", "properties": { "deltaRA-deltaDEC": { "description": "Covariance between the differences in right ascension and the differences in declination", "type": "number" }, "deltaRAcosDEC-deltaDEC": { "description": "Covariance between the differences in right ascension times the cosine of the declination and the differences in declination", "type": "number" } } }, "numberOfResiduals": { "description": "Number of observations or differences", "type": "integer" }, "minimum": { "description": "Minimum values of the differences", "type": "object", "properties": { "deltaRA": { "description": "Minimum value of the differences between the observation and the computation (O-C) in right ascension, expressed in arcseconds", "$ref": "#/components/schemas/angle" }, "deltaRAcosDEC": { "description": "Minimum value of the differences between the observation and the computation (O-C) in right ascension times the cosine of the declination, expressed in arcseconds", "$ref": "#/components/schemas/angle" }, "deltaDEC": { "description": "Minimum value of the differences between the observation and the computation (O-C) in declination, expressed in arcseconds", "$ref": "#/components/schemas/angle" } } }, "maximum": { "description": "Maximum values of the differences", "type": "object", "properties": { "deltaRA": { "description": "Maximum value of the differences between the observation and the computation (O-C) in right ascension, expressed in arcseconds", "$ref": "#/components/schemas/angle" }, "deltaRAcosDEC": { "description": "Maximum value of the differences between the observation and the computation (O-C) in right ascension times the cosine of the declination, expressed in arcseconds", "$ref": "#/components/schemas/angle" }, "deltaDEC": { "description": "Maximum value of the differences between the observation and the computation (O-C) in declination, expressed in arcseconds", "$ref": "#/components/schemas/angle" } } }, "meanArithmeticError": { "description": "Mean arithmetic of the differences", "type": "object", "properties": { "deltaRA": { "description": "Mean arithmetic of the differences between the observation and the computation (O-C) in right ascension, expressed in arcseconds", "$ref": "#/components/schemas/angle" }, "deltaRAcosDEC": { "description": "Mean arithmetic of the differences between the observation and the computation (O-C) in right ascension times the cosine of the declination, expressed in arcseconds", "$ref": "#/components/schemas/angle" }, "deltaDEC": { "description": "Mean arithmetic of the differences between the observation and the computation (O-C) in declination, expressed in arcseconds", "$ref": "#/components/schemas/angle" } } }, "meanAbsoluteError": { "description": "Mean absolute error of the differences", "type": "object", "properties": { "deltaRA": { "description": "Mean absolute error (MAE) in right ascension, expressed in arcseconds : sum of the absolute differences in right ascension divided by the number of observations", "$ref": "#/components/schemas/angle" }, "deltaRAcosDEC": { "description": "Mean absolute error (MAE) in right ascension, expressed in arcseconds : sum of the absolute differences in right ascension times the cosine of the declination divided by the number of observations", "$ref": "#/components/schemas/angle" }, "deltaDEC": { "description": "Mean absolute error (MAE) in declination, expressed in arcseconds : sum of the absolute differences in declination divided by the number of observations", "$ref": "#/components/schemas/angle" } } }, "rootMeanSquareDeviation": { "description": "Root-mean-square deviation (RMS) of the differences", "type": "object", "properties": { "deltaRA": { "description": "Root-mean-square deviation (RMS) of the differences in right ascension, expressed in arcseconds", "$ref": "#/components/schemas/angle" }, "deltaRAcosDEC": { "description": "Root-mean-square deviation (RMS) of the differences in right ascension times the cosine of the declination, expressed in arcseconds", "$ref": "#/components/schemas/angle" }, "deltaDEC": { "description": "Root-mean-square deviation (RMS) in declination, expressed in arcseconds", "$ref": "#/components/schemas/angle" } } }, "standardDeviation": { "description": "Population standard deviation of the differences", "type": "object", "properties": { "deltaRA": { "description": "Population standard deviation of the differences in right ascension, expressed in arcseconds", "$ref": "#/components/schemas/angle" }, "deltaRAcosDEC": { "description": "Population standard deviation of the differences in right ascension, expressed in arcseconds", "$ref": "#/components/schemas/angle" }, "deltaDEC": { "description": "Population standard deviation of the differences in declination, expressed in arcseconds", "$ref": "#/components/schemas/angle" } } } } } } } }, "example": "EXAMPLERESIDUAL" } } } }, "500": { "$ref": "#/components/responses/500" }, "400": { "$ref": "#/components/responses/400_get" } } } } } }