Horizons Ephemeris Examples

The JPL Horizons platform provides ephemeris data as Cartesian state vectors, osculating orbital elements, and other representations. The precise REST API accepted by the JPL Horizons servers is implemented in Julia with HorizonsAPI.jl.

using HorizonsAPI

fetch_vectors(399; format="text") # Earth's position w.r.t. the solar system barycenter

HTTP.Messages.Response:
"""
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 30 Dec 2024 22:56:23 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive

API VERSION: 1.2
API SOURCE: NASA/JPL Horizons API



*******************************************************************************
Ephemeris / API_USER Mon Dec 30 14:56:23 2024 Pasadena, USA      / Horizons
*******************************************************************************
Target body name: Earth (399)                     {source: DE441}
Center body name: Earth (399)                     {source: DE441}
Center-site name: BODY CENTER
*******************************************************************************
Start time      : A.D. 2022-Jan-01 10:00:00.0000 TDB
Stop  time      : A.D. 2022-Jan-02 00:00:00.0000 TDB
Step-size       : 60 minutes
*******************************************************************************
Center geodetic : 0.0, 0.0, 0.0                   {E-lon(deg),Lat(deg),Alt(km)}
Center cylindric: 0.0, 0.0, 0.0                   {E-lon(deg),Dxy(km),Dz(km)}
Center radii    : 6378.137, 6378.137, 6356.752 km {Equator_a, b, pole_c}
Output units    : KM-S
⋮
9098-byte body
"""

The CENTER parameter specifies the ephemeris reference position.

fetch_vectors(499; format="text", CENTER="@399") # Mars' position w.r.t. Earth

HTTP.Messages.Response:
"""
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 30 Dec 2024 22:56:23 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive

API VERSION: 1.2
API SOURCE: NASA/JPL Horizons API



*******************************************************************************
Ephemeris / API_USER Mon Dec 30 14:56:23 2024 Pasadena, USA      / Horizons
*******************************************************************************
Target body name: Mars (499)                      {source: mar097}
Center body name: Earth (399)                     {source: DE441}
Center-site name: BODY CENTER
*******************************************************************************
Start time      : A.D. 2022-Jan-01 10:00:00.0000 TDB
Stop  time      : A.D. 2022-Jan-02 00:00:00.0000 TDB
Step-size       : 60 minutes
*******************************************************************************
Center geodetic : 0.0, 0.0, 0.0                   {E-lon(deg),Lat(deg),Alt(km)}
Center cylindric: 0.0, 0.0, 0.0                   {E-lon(deg),Dxy(km),Dz(km)}
Center radii    : 6378.137, 6378.137, 6356.752 km {Equator_a, b, pole_c}
Output units    : KM-
⋮
9099-byte body
"""

The response from the Horizons API contains a lot of information! To more simply fetch and inspect ephemeris data from JPL Horizons servers, use the ephemeris method in HorizonsEphemeris.jl.

using Dates, HorizonsEphemeris

ephemeris("earth", now())

(t = [2.460675455831146e6], cal = InlineStrings.String31[" A.D. 2024-Dec-30 22:56:23.8110"], x = [-0.1664272795144508], y = [0.8855444042881202], z = [0.3840705066066824], ẋ = [-0.01725321594883406], ẏ = [-0.00264311856721558], ż = [-0.001145914095578868])

The output of ephemeris is a NamedTuple, so you can easily pass it along to DataFrames.jl for convenient inspection & data processing. Note the wrt keyword argument as well; it is a simplified interface to the Horizons API CENTER argument.

using DataFrames

data = DataFrame(
    ephemeris("earth", now() - Year(5), now() + Year(5), Day(14); wrt="jupiter")
)

This example wouldn't be complete without some plotting!

using Plots

figure = plot(
    data.x, data.y;
    xlabel="X (KM)", ylabel="Y (KM)", label=:none,
    title="Earth's Position w.r.t. Jupiter"
);

Reference

You can find more information about HorizonsAPI and HorizonsEphemeris at their respective documentation pages, which are linked above in the website's navigation bar. For convenience, their pages are each linked below as well.