Wolfram Research

Function Repository Resource:

HorizonsEphemerisData (1.0.0) current version: 1.1.0 »

Source Notebook

Import ephemeris data from the Jet Propulsion Laboratory Horizons System

Contributed by: Truman Tapia  |  Truman Tapia

ResourceFunction["HorizonsEphemerisData"][etype, query, properties]

queries Horizons System and gives the values of the properties for the given query and ephemeris type etype.

Details

ResourceFunction["HorizonsEphemerisData"] retrieves data from Horizons System using Horizons API.
Horizons System has ephemerides of planets, natural satellites, spacecrafts, asteroids, comets and several dynamical points.
The parameter etype can take one of the following values: "State", "OrbitalElements" and "Observer". Each ephemeris type has its own query parameters and properties.
Queries can be specified in the following forms:
targetquery with target specified with default parameter values
{target, <|"param1"->val1, "param1"->val2, …|>}query with detailed parameters specified
<|"Target"->target, "param1"->val1, "param1"->val2, …|>query with detailed parameters specified
The valid "parami" parameters for query of a given etype can be obtained by evaluating ResourceFunction["HorizonsEphemerisData"][etype, "QueryParameters"].
The properties available for a given etype can be obtained by evaluating ResourceFunction["HorizonsEphemerisData"][etype, "Properties"].
The following are query parameters of the "State" ephemeris type:
"Center"Solar System Barycentercenter of the reference frame and reference place to apply corrections.
"Dates"Nowdates used in the ephemeris output.
"Frame""ICRF"frame used in the ephemeris output. Can take the values: "BodyJ2000Equinox", "BodyB1950Equinox", "ICRF", "FK4", "EclipticICRF" and "EclipticFK4".
"Corrections"Nonecorrections applied. Can take the values: None, "LightTime" and "LightTime+StellarAberration".
Not all the properties of the "State" ephemeris type can be obtained in one call.
Following the query parameters of the "OrbitalElements" ephemeris type:
"Center"Solar System Barycentercenter of the reference frame.
"Dates"Nowdates used in the ephemeris output.
"Frame""ICRF"frame used in the ephemeris output. Can take the values: "BodyJ2000Equinox", "BodyB1950Equinox", "ICRF", "FK4", "EclipticICRF" and "EclipticFK4".
Following the query parameters of the "Observer" ephemeris type:
"Center"Herecenter of observation.
"Dates"Nowdates used in the ephemeris output.
"EarthAtmosphericRefraction"Falsewhether or not apply corrections due to the Earth's atmosphere.
"SkipDay"Falsewhether or not skip dates during the day in the output.
"RiseTransitSetOnly"Falsereturn ephemeris data only when rise, transit or set is happening.
"MinElevation"-90return ephemeris data only when the target elevation is higher than the value specified in degrees.
"MaxRelativeAirmass"38return ephemeris data only when relative airmass is less than the specified value.
"MinMaxSolarElongation"{0,180}return ephemeris data only when the target's solar elongation angle is inside the limits specified in degrees.
"MaxAngularRate"Infinityreturn ephemeris data only when the target's angular rate is less than the value specified in "Arcseconds"/"Hours". The value can be a Quantity too.
The target and the parameter "Center" can be specified as Entity, GeoPosition or String. Entity can be an object in the solar system. Also, entities of the type "SolarSystemFeature" are supported. GeoPosition can be a position on Earth or other object of the solar system. String can be an Horizon's id used to identify an object of the solar system, two-line element set (TLE) or a keyword.
The ephemeris of an object defined by a TLE can be extrapolated only 14 days before and after the data.
The query parameter "Dates" can be specified as a single DateObject, a List of DateObjects or with the syntax {StartDate, EndDate, increment}. To get the ephemeris of a big list of dates use the syntax {StartDate, EndDate, increment}.
The following modifiers can be used in ResourceFunction["HorizonsEphemerisData"][etype, query, properties, "modifier"]:
"Association"a nested association with dates as keys on the first level and properties as keys on the second level
"Dataset"a dataset containing the same structure of the "Association" modifier

Examples

Basic Examples (3) 

Get the Cartesian position of Mars with default parameters:

In[1]:=
ResourceFunction["HorizonsEphemerisData"]["State", Entity["Planet", "Mars"], "Position"]
Out[1]=

Get the position of Mars for a specific date:

In[2]:=
ResourceFunction["HorizonsEphemerisData", ResourceVersion->"1.0.0"]["State", {Entity["Planet", "Mars"], <|
   "Dates" -> Now + Quantity[12, "Hours"]|>}, "Position"]
Out[2]=

Define a location on Earth:

In[3]:=
pos = Entity["City", {"Riobamba", "Chimborazo", "Ecuador"}][
   "Position"];

Get the azimuth and elevation of the Tycho crater as seen from Riobamba city for the next 12 hours:

In[4]:=
ResourceFunction["HorizonsEphemerisData", ResourceVersion->"1.0.0"]["Observer", <|
  "Target" -> Entity["SolarSystemFeature", "TychoMoon"], "Center" -> pos, "Dates" -> {Now, Now + Quantity[12, "Hours"], Quantity[10, "Minutes"]}|>, All, "Dataset"]
Out[4]=

Get the orbital elements of Saturn's moon Pandora for a specific list of dates:

In[5]:=
ResourceFunction["HorizonsEphemerisData", ResourceVersion->"1.0.0"]["OrbitalElements", {Entity["PlanetaryMoon", "Pandora"], <|"Center" -> Entity["Planet", "Saturn"], "Dates" -> {DateObject[{2000, 1, 10, 0, 0, 0}, "Instant", "Gregorian", 0.`], DateObject[{2000, 1, 11, 0, 0, 0}, "Instant", "Gregorian", 0.`]}|>}, All, "Association"]
Out[5]=

Scope (2) 

Define a location on Mars:

In[6]:=
pos = GeoPosition[{-4.5, -137.4}, Entity["Planet", "Mars"]];

Get all the properties of the "Observer" ephemeris type for this location on Mars seen from a location in Earth, applying corrections due to atmospheric refraction and skipping the dates when it is day:

In[7]:=
ResourceFunction["HorizonsEphemerisData", ResourceVersion->"1.0.0"]["Observer", {pos, <|"Center" -> Here, "EarthAtmosphericRefraction" -> True, "SkipDay" -> True, "Dates" -> {Now, Now + Quantity[24, "Hours"], Quantity[1, "Hours"]}|>}, All, "Dataset"]
Out[7]=

Define a TLE:

In[8]:=
tle = "1 11416U 79057A   04363.14000343  .00000107  00000-0  56512-4 0  5663
2 11416  98.5474  30.2466 0011085  51.8150 308.4039 14.31601235328172
1 11416U 79057A   04363.62924579  .00000108  00000-0  56923-4 0  5681
2 11416  98.5473  30.7281 0011072  50.5542 309.6625 14.31601418328243
1 11416U 79057A   04364.67762161  .00000130  00000-0  65019-4 0  5674
2 11416  98.5470  31.7599 0011009  47.6294 312.5820 14.31602047328399
1 11416U 79057A   04365.65610603  .00000127  00000-0  64027-4 0  5704
2 11416  98.5468  32.7230 0010941  45.1722 315.0344 14.31602333328535
1 11416U 79057A   04366.42491512  .00000132  00000-0  65727-4 0  5687
2 11416  98.5467  33.4797 0010912  43.1795 317.0244 14.31602636328645
1 11416U 79057A   04366.70448198  .00000129  00000-0  64650-4 0  5691
2 11416  98.5464  33.7545 0010857  42.9225 317.2802 14.31602697328682";

Get the position of the object defined by this TLE seen from the ISS. The Horizons ID of the ISS is -125544 (see Possible Issues section). The character "@" means the center of the object in the Horizons System:

In[9]:=
ResourceFunction["HorizonsEphemerisData", ResourceVersion->"1.0.0"]["State", {tle, <|"Center" -> "@-125544", "Dates" -> {DateObject[{2005, 1, 9}], DateObject[{2005, 1, 10}], Quantity[1, "Hours"]}, "Frame" -> "ICRF", "Corrections" -> None|>}, "Position", "Dataset"]
Out[9]=

Possible Issues (2) 

When several objects in the Horizons System match the target specification, a table with the matched objects is printed and Null is returned:

In[10]:=
ResourceFunction["HorizonsEphemerisData"]["State", "ISS", All]

Use the ID to uniquely identify the object:

In[11]:=
ResourceFunction["HorizonsEphemerisData"]["State", "-125544", All]
Out[11]=

Neat Examples (2) 

Get the trajectory of the Cassini spacecraft around Saturn (the Horizons ID of Cassini is -82):

In[12]:=
cassini = ResourceFunction["HorizonsEphemerisData"][
   "State", {"-82", <|"Center" -> Entity["Planet", "Saturn"], "Dates" -> {DateObject[{1997, 10, 16, 0, 0, 0.`}, "Instant", "Gregorian", 0.`], DateObject[{2017, 9, 15, 0, 0, 4.`}, "Instant", "Gregorian", 0.`], Quantity[1, "Days"]}|>}, "Position"];

Plot the fly of Cassini:

In[13]:=
ListLinePlot3D[{cassini[[All, 2 ;;]]}, BoxRatios -> Automatic, PlotRange -> All, PlotStyle -> {Opacity[0.1, Blue]}, PlotRange -> All]
Out[13]=

Version History

  • 1.1.0 – 05 July 2022
  • 1.0.0 – 17 May 2022

Source Metadata

Related Resources

License Information