Skip to content

MPC Asteroids

MPC asteroid orbit catalog download, parsing, lookup, and state computation.

See the MPC Asteroids User Guide for concepts and usage.

Download

Download Minor Planet Center (MPC) asteroid orbit catalog.

Provides a helper to fetch the mpcorb_extended.json.gz file from the MPC data centre. Network errors are propagated to the caller so that higher-level code (e.g. :func:load_mpc_asteroids) can decide on fallback behaviour.

MPC_URL = 'https://minorplanetcenter.net/Extended_Files/mpcorb_extended.json.gz' module-attribute

Default URL for the MPC extended orbit catalog (gzipped JSON).

download_mpc_file(filepath, *, url=MPC_URL, timeout=_DEFAULT_TIMEOUT)

Download the MPC extended orbit catalog to filepath.

Creates parent directories if they do not exist. On success the downloaded binary data is written to filepath and the resolved path is returned.

Parameters:

Name Type Description Default
filepath str | Path

Destination path for the downloaded file.

 required
url str

URL to fetch. Defaults to :data:MPC_URL.

 MPC_URL
timeout float

HTTP timeout in seconds. Defaults to 300.

 _DEFAULT_TIMEOUT

Returns:

Name Type Description
Resolved Path

class:~pathlib.Path to the written file.

Raises:

Type Description
HTTPStatusError

If the server returns a non-2xx status.
TransportError

On network-level failures (DNS, timeout, etc.).

Parsers

Parsing utilities for MPC asteroid orbit data.

Provides helpers to decode MPC packed epoch dates and convert the mpcorb_extended.json.gz file into a Polars DataFrame with computed Julian Date epochs.

load_mpc_json_to_dataframe(filepath)

Load an MPC mpcorb_extended.json.gz file into a Polars DataFrame.

Decompresses the gzipped JSON, extracts the relevant orbital element columns, and derives the epoch_jd column. The MPC Epoch field may be either a 5-character packed date string (older format) or a Julian Date float (current format); both are handled transparently.

Parameters:

Name Type Description Default
filepath str | Path

Path to the .json.gz file.

 required

Returns:

Type Description
DataFrame

Polars DataFrame with columns: number, name,
DataFrame

principal_desig, epoch_packed, epoch_jd, a,
DataFrame

e, i, node, peri, M, n, H.

Raises:

Type Description
FileNotFoundError

If the file does not exist.

packed_mpc_epoch_to_jd(packed)

Convert an MPC packed epoch to Julian Date (TT).

Parameters:

Name Type Description Default
packed str

A 5-character MPC packed epoch string.

 required

Returns:

Type Description
float

Julian Date (TT) as a float.

Examples:

>>> packed_mpc_epoch_to_jd("J9611")  # 1996-01-01
2450083.5

unpack_mpc_epoch(packed)

Decode an MPC 5-character packed date to (year, month, day).

The encoding uses five characters:

  • Position 0: century (I = 18, J = 19, K = 20)
  • Positions 1–2: two-digit year within the century
  • Position 3: month (1–9 for Jan–Sep, A = Oct, B = Nov, C = Dec)
  • Position 4: day (1–9, A = 10, … V = 31)

Parameters:

Name Type Description Default
packed str

A 5-character MPC packed epoch string.

 required

Returns:

Type Description
tuple[int, int, int]

Tuple of (year, month, day) as integers.

Raises:

Type Description
ValueError

If the packed string is malformed.

Examples:

>>> unpack_mpc_epoch("K24BN")
(2024, 11, 23)
>>> unpack_mpc_epoch("J9611")
(1996, 1, 1)

Providers

Factory functions for loading the MPC asteroid orbit catalog.

Provides convenience functions for loading the Minor Planet Center extended orbit catalog as a Polars DataFrame:

  • :func:load_mpc_asteroids: Load from cache, downloading fresh data when stale.
  • :func:load_mpc_from_file: Load from an arbitrary file path.

load_mpc_asteroids(filepath=None, *, max_age_days=_DEFAULT_MAX_AGE_DAYS)

Load the MPC asteroid catalog from a local cache, downloading when stale.

Checks whether the cached file at filepath exists and is younger than max_age_days. If the file is missing or stale, a fresh copy of mpcorb_extended.json.gz is downloaded from the MPC.

Parameters:

Name Type Description Default
filepath str | Path | None

Path to the cached MPC file. When None (the default), uses <cache_dir>/datasets/mpc/mpcorb_extended.json.gz.

 None
max_age_days float

Maximum acceptable age of the cached file in days. Defaults to 7.

 _DEFAULT_MAX_AGE_DAYS

Returns:

Type Description
DataFrame

Polars DataFrame with asteroid orbital elements.

Raises:

Type Description
RuntimeError

If the download fails and no cached file exists.

Examples:

from astrojax.datasets import load_mpc_asteroids
df = load_mpc_asteroids()
print(df.shape)
print(df.head())

load_mpc_from_file(filepath)

Load MPC asteroid data from a local file.

Parameters:

Name Type Description Default
filepath str | Path

Path to an mpcorb_extended.json.gz file.

 required

Returns:

Type Description
DataFrame

Polars DataFrame with asteroid orbital elements.

Raises:

Type Description
FileNotFoundError

If the file does not exist.

Examples:

from astrojax.datasets import load_mpc_from_file
df = load_mpc_from_file("/path/to/mpcorb_extended.json.gz")
print(df.shape)

State & Lookup

Heliocentric ecliptic state computation for MPC asteroids.

Provides functions to propagate asteroid orbits from MPC Keplerian elements and compute heliocentric ecliptic J2000 Cartesian state vectors at arbitrary Julian dates.

All computational functions use JAX primitives and are compatible with jax.jit, jax.vmap, and jax.grad.

asteroid_state_ecliptic(epoch_jd, oe, target_jd, *, use_au=False)

Compute heliocentric ecliptic J2000 state for an asteroid.

Given an epoch Julian Date (TT), orbital elements from the MPC catalog, and a target Julian Date (TT), propagates the mean anomaly forward and computes the full Cartesian state vector.

Since MPC orbital elements are referenced to the ecliptic J2000 frame, the output is directly in heliocentric ecliptic J2000 coordinates.

Parameters:

Name Type Description Default
epoch_jd ArrayLike

Epoch Julian Date (TT) at which the orbital elements are defined.

 required
oe ArrayLike

Orbital elements [a_AU, e, i_deg, node_deg, peri_deg, M_deg]. Semi-major axis in AU, angles in degrees.

 required
target_jd ArrayLike

Target Julian Date (TT) at which to compute the state.

 required
use_au bool

If True, return position in AU and velocity in AU/day. Default False returns SI units (m, m/s).

 False

Returns:

Type Description
Array

Heliocentric ecliptic J2000 state [x, y, z, vx, vy, vz].
Array

Units depend on use_au: SI (m, m/s) or (AU, AU/day).

Examples:

import jax.numpy as jnp
from astrojax.datasets import asteroid_state_ecliptic

# Ceres-like elements (approximate)
oe = jnp.array([2.769, 0.0755, 10.59, 80.31, 73.60, 77.37])
state = asteroid_state_ecliptic(2460000.5, oe, 2460100.5)

get_asteroid_ephemeris(df, identifier)

Look up an asteroid's orbital elements from the MPC DataFrame.

Searches by number (if identifier is an int or numeric string) or by name (if identifier is a non-numeric string).

Parameters:

Name Type Description Default
df DataFrame

Polars DataFrame as returned by :func:load_mpc_asteroids.

 required
identifier int | str

Asteroid number (int or numeric str) or name (str).

 required

Returns:

Type Description
dict

Dictionary with keys: name, number, principal_desig,
dict

epoch_jd, a, e, i, node, peri, M,
dict

n, H.

Raises:

Type Description
KeyError

If the asteroid is not found.

Examples:

from astrojax.datasets import load_mpc_asteroids, get_asteroid_ephemeris
df = load_mpc_asteroids()
ceres = get_asteroid_ephemeris(df, 1)
print(ceres["name"])  # "Ceres"