omnilab/horizons API reference

Omnilab\Horizons

HorizonsSource class

final class HorizonsSource extends HttpSource HorizonsSource.php:38

JPL Horizons (ssd.jpl.nasa.gov/api/horizons.api): the ephemeris of a body of the solar system - a planet, a moon, the Sun, an asteroid, a comet, a spacecraft - seen from a place on the Earth over a period, as series: its right ascension and declination, azimuth and elevation, airmass, apparent magnitude and surface brightness, illuminated fraction, angular diameter, its distances to the observer and to the Sun and their rates, its solar elongation and phase angle.

A series is one variable at a place over a time, and an ephemeris is that once the body is said: each variable names its body before its quantity, "<body>:<quantity>" - "499:ra" (Mars), "301:elevation" (the Moon), "jpl.sbdb:99942:distance" (Apophis), "jpl.sbdb:1P:magnitude". A body is a Horizons id (a number: 10 the Sun, 301 the Moon, 499 Mars, -74 the Mars Reconnaissance Orbiter), a small body of the jpl.sbdb scheme (a number, a designation, a comet's, an SPK-ID, a name), or Horizons' own command ("DES=2004 MN4;"). One call per body, whatever its quantities.

No key. JPL's fair use: one request at a time, a User-Agent that names the caller (set "mailto"); the calls are spaced by 0.2 s by default.

const BASE_URI = 'https://ssd.jpl.nasa.gov/api/'

const QUANTITIES = ['ra' => [1, '~^R\.A\._*\(ICRF\)$~', 'deg', 'Right ascension (ICRF, astrometric)'], 'dec' => [1, '~^DEC_*\(ICRF\)$~', 'deg', 'Declination (ICRF, astrometric)…

The quantities a variable names: quantity => [Horizons' quantity code, the pattern of its column, unit, label]. Angles in degrees (ANG_FORMAT=DEG), distances in au, rates in km/s.

HorizonsSource::__construct()

public function __construct(HttpClientInterface $http, string $baseUri = self::BASE_URI, array $headers = [], float $throttle = 0.2)

HorizonsSource::getName()

public function getName(): string

HorizonsSource::capabilities()

public function capabilities(): array

HorizonsSource::series()

public function series(SeriesQuery $query): array

One series per variable, "<body>:<quantity>", in the order asked: the body seen from the query's Point (its elevation in metres, 0 when unknown), each step from the start of the period to its end (an end at midnight is its whole day; no start is today, no end a day later). The times are UT, given in the query's time zone when it names one. A body Horizons does not find answers a series without points; a name several bodies share is a ProviderException that lists them.

HorizonsSource::command()

public static function command(Identifier|string $body): string

Horizons' command for a body: a Horizons id as it is ("499", "-74"), a small body of the jpl.sbdb scheme as a small-body search ("433;", "DES=2004 MN4;", "DES=1P; CAP;" - a comet's latest apparition -, "NAME=Eros;", an SPK-ID "DES=20000433;"), anything else as Horizons reads it. An identifier of another scheme is refused.

HorizonsSourceFactory class

final class HorizonsSourceFactory extends SourceFactory HorizonsSourceFactory.php:19

JPL Horizons: the ephemeris of a body of the solar system seen from a place on the Earth, as series - no key needed.

options: mailto: 'support@glitchr.io' # in the User-Agent: JPL's fair use asks an application-specific one with a contact throttle: 0.2 # seconds between two calls: JPL asks one request at a time base_uri: 'https://ssd.jpl.nasa.gov/api/'

Options