jplephem: JPL Planetary Ephemeris Access

2.24 · active · verified Mon Apr 13

jplephem (version 2.24) is a Python library that enables users to load and interpolate positions and velocities from JPL Planetary and Lunar Ephemerides (.bsp files). It provides a programmatic interface to NASA JPL's highly accurate ephemeris data, often used in astronomy and astrodynamics. The library is actively maintained with releases occurring as needed for updates or bug fixes.

Warnings

gotcha jplephem requires external JPL ephemeris (.bsp) data files, which are often large (hundreds of MBs) and are NOT bundled with the library. These files must be downloaded separately from JPL's FTP server or NASA's PDS.
Fix: Download required `.bsp` files (e.g., `de421.bsp`, `de440.bsp`) from `ftp://ssd.jpl.nasa.gov/pub/eph/planets/bsp/` or `https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/` and provide their path to `jplephem.ephem.Ephemeris` or `jplephem.spk.SPK`.
gotcha jplephem internally operates with Julian Dates (JD). While a helper exists for `datetime` conversion, users should be aware of this time system.
Fix: Use `jplephem.jpllib.convert_datetime_to_jd()` to safely convert Python `datetime` objects to the required Julian Date format for ephemeris calculations.
gotcha Output positions are typically in Astronomical Units (AU) and velocities in AU per day by default. Be mindful of these units when interpreting results.
Fix: Always check the documentation for the specific method (e.g., `position()`, `velocity()`) to confirm the units of the returned array. Perform explicit unit conversions if other units are required for your application.

Install

pip install jplephem Install stable version

Imports

Ephemeris
```
from jplephem.ephem import Ephemeris
```
Used for loading and interpolating from standard JPL DE (.bsp) kernels.
SPK
```
from jplephem.spk import SPK
```
Used for loading and interpolating from SPK (.bsp) kernels, often used for spacecraft and smaller bodies.
convert_datetime_to_jd
```
from jplephem.jpllib import convert_datetime_to_jd
```
Helper function to convert Python datetime objects to Julian Dates, which are used internally by jplephem.

Quickstart

This quickstart demonstrates how to load a JPL ephemeris (.bsp) file and compute the position and velocity of a celestial body. **Crucially, the .bsp file itself is NOT bundled with the library and must be downloaded separately.** Common files like `de421.bsp` or `de440.bsp` can be found on JPL's FTP server. The example checks for the file specified by the `JPLEPHEM_BSP_PATH` environment variable (defaulting to 'de421.bsp' in the current directory) and proceeds with a calculation if found, otherwise it prints an explanatory error.

import os
from datetime import datetime
from jplephem.ephem import Ephemeris
from jplephem.jpllib import convert_datetime_to_jd

# WARNING: Ephemeris data files are large and NOT bundled with the library.
# You must download a JPL .bsp ephemeris file (e.g., 'de421.bsp' or 'de440.bsp')
# from the JPL FTP server (ftp://ssd.jpl.nasa.gov/pub/eph/planets/bsp/)
# or NASA PDS (https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/).
#
# Set the environment variable JPLEPHEM_BSP_PATH to the path of your downloaded file.
# For example: export JPLEPHEM_BSP_PATH="/path/to/your/de421.bsp"

bsp_path = os.environ.get('JPLEPHEM_BSP_PATH', 'de421.bsp')

if not os.path.exists(bsp_path):
    print(f"Error: Ephemeris file '{bsp_path}' not found.")
    print("Please download a .bsp kernel (e.g., de421.bsp) and set the")
    print("JPLEPHEM_BSP_PATH environment variable, or place the file in the current directory.")
    print("Skipping ephemeris calculation.")
else:
    try:
        ephemeris = Ephemeris(bsp_path)
        print(f"Successfully loaded ephemeris from: {bsp_path}")

        # Calculate position of Earth-Moon Barycenter (body 3) relative to
        # Solar System Barycenter (body 0) on January 1, 2000.
        target_date = datetime(2000, 1, 1, 12, 0, 0) # Noon UTC
        jd = convert_datetime_to_jd(target_date)

        # The 'observer' is the body from which the 'target' is observed.
        # Here, observer=0 (Solar System Barycenter), target=3 (Earth-Moon Barycenter).
        # The result is a 3-element NumPy array: [x, y, z] in AU.
        position_vector = ephemeris.position(3, 0, jd)

        print(f"\nDate: {target_date.isoformat()}")
        print(f"Julian Date: {jd}")
        print(f"Position of Earth-Moon Barycenter relative to SSB (AU):")
        print(f"  x={position_vector[0]:.6f}, y={position_vector[1]:.6f}, z={position_vector[2]:.6f}")

        # Example with velocity:
        velocity_vector = ephemeris.velocity(3, 0, jd)
        print(f"Velocity of Earth-Moon Barycenter relative to SSB (AU/day):")
        print(f"  vx={velocity_vector[0]:.6f}, vy={velocity_vector[1]:.6f}, vz={velocity_vector[2]:.6f}")

    except Exception as e:
        print(f"An error occurred while using the ephemeris: {e}")

view raw JSON →