Wolfram Function Repository

Instant-use add-on functions for the Wolfram Language

Function Repository Resource:

 HorizonsEphemerisData

Source Notebook

Import ephemeris data from the Jet Propulsion Laboratory Horizons System

Contributed by: 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: "ICRF", "FK4", "EclipticJ2000", "EclipticB1950" and “CenterBodyEquator”.
"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: “ICRF”, “FK4”, “EclipticJ2000”, “EclipticB1950” and “CenterBodyEquator”.
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"]["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"]["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"]["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"]["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"]["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 Dataset is returned:

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

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]=

Publisher

Truman Tapia

Version History

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

Source Metadata

  • Citation:
    • Giorgini, J.D., JPL Solar System Dynamics Group, "NASA/JPL Horizons On-Line Ephemeris System." https://ssd.jpl.nasa.gov/horizons. Data retrieved 2022-04-16.
    • Giorgini, J. D., Chodas, P.W., Yeomans, D.K., "Orbit Uncertainty and Close-Approach Analysis Capabilities of the Horizons On-Line Ephemeris System." 33rd AAS/DPS meeting in New Orleans, LA, Nov 26, 2001–Dec 01, 2001.
    • Giorgini, J. D, Yeomans, D.K., "On-Line System Provides Accurate Ephemeris and Related Data." NASA Tech Briefs, NPO-20416, p. 48, 1999.
    • Giorgini, J.D., Yeomans, D.K., Chamberlin, A.B., Chodas, P.W., Jacobson, R.A., Keesey, M.S., Lieske, J.H., Ostro, S.J., Standish, E.M., Wimberly, R.N., "JPL’s On-Line Solar System Data Service." Bulletin of the American Astronomical Society, Vol 28, No. 3, p. 1158, 1996.

Related Resources

License Information