ephem API

The Sun and Moon from JPL DE440: where they are, what they do on a day, when they reach an altitude, and where to stand so one sits on a landmark. JSON over HTTPS, CORS open, no key. Every answer is checked against an independent implementation (Skyfield for the sky, PROJ and GeographicLib for geometry, NOAA test values and pygeomag for the magnetic field) and states the conventions it used.

Where are the Sun and Moon right now?

curl 'https://ephem.ivar.workers.dev/v1/position?lat=40.7&lon=-74'

When do they rise and set, and when is twilight, on a local day?

curl 'https://ephem.ivar.workers.dev/v1/day?lat=40.7&lon=-74&date=2026-11-16&tz=America/New_York'

Where do I stand so the Moon sits on the Statue of Liberty?

curl 'https://ephem.ivar.workers.dev/v1/alignment?body=moon&targetLat=40.68925&targetLon=-74.0445&targetHeight=70&targetHeightRef=msl&height=5&heightRef=msl&start=2026-11-17T03:44:30Z&end=2026-11-17T03:46:00Z&stepSeconds=5&maxDistanceKm=8'

Rules

Endpoints

One question each. GET unless noted. * = required.

/v1/position
Where are the Sun and Moon at an instant? Topocentric Sun and Moon at one instant (default now): azimuth, true and apparent altitude, rates, RA/Dec, distance, angular radius, Moon phase and bright limb (from celestial north and from the local vertical).
Parameters: lat*, lon*, height, heightRef, time, temperature, pressure, horizon, dut1
Example: /v1/position?lat=40.7&lon=-74&time=2026-11-17T03:45:00Z
/v1/track
What paths do they trace across the sky? Sun and Moon azimuth, true and apparent altitude on a UTC grid (≤ 8 days, ≤ 1 441 samples), columnar; each sample equals /v1/position at that instant.
Parameters: lat*, lon*, height, heightRef, start*, end*, stepSeconds, temperature, pressure, horizon, dut1
Example: /v1/track?lat=40.7&lon=-74&start=2026-11-16T00:00:00Z&end=2026-11-17T00:00:00Z
/v1/day
What happens on a local day? Rise, set, transit, civil / nautical / astronomical twilight, golden and blue hour for the Sun and Moon, sorted by time, with a conventions block (aim, horizon, dip, refraction, thresholds, geoid).
Parameters: lat*, lon*, height, heightRef, date*, tz*, temperature, pressure, horizon, horizonProfile, aim, dut1
Example: /v1/day?lat=40.7&lon=-74&date=2026-11-16&tz=America/New_York
/v1/crossing
When does a body reach a given altitude or skyline? Every instant in a window (≤ 31 days) or a local date when the centre, a limb or the Moon's lit-area centroid (aim) reaches a true or apparent altitude, or a skyline profile.
Parameters: lat*, lon*, height, heightRef, body*, altitude, altitudeType, horizonProfile, direction, start, end, date, tz, temperature, pressure, dut1, include, aim
Example: /v1/crossing?body=moon&lat=40.6985&lon=-73.999&height=5&heightRef=msl&altitude=0.87&altitudeType=apparent&direction=set&start=2026-11-16T00:00:00Z&end=2026-11-18T00:00:00Z
/v1/alignment
Where do I stand so the body sits on a landmark? Per instant, the standing point from which the Sun or Moon (centre, a limb, or the Moon's lit-area centroid: aim) sits on the target, with distance, bearing, rates and the eye's heights; with lat/lon (a fixed spot), also when it passes the target from there.
Parameters: body*, targetLat*, targetLon*, targetHeight*, targetHeightRef, height, heightRef, start*, end*, stepSeconds, maxDistanceKm, temperature, pressure, dut1, lat, lon, include, aim
Example: /v1/alignment?body=moon&targetLat=40.68925&targetLon=-74.0445&targetHeight=70&targetHeightRef=msl&height=5&heightRef=msl&start=2026-11-17T03:44:30Z&end=2026-11-17T03:46:00Z&stepSeconds=5&maxDistanceKm=8
POST /v1/alignment/search
Every pass over an area I can stand in, over months. Every pass in [start, end) (≤ 400 days) when the alignment standing point lies inside a region you can stand in, with exact entry / exit per in-region segment and, per pass, the body's azimuth and apparent altitude, the Moon's illuminated fraction and the Sun's altitude. One call instead of crossing → alignment → polygon clip → position. The JSON body uses the same names as /v1/alignment's query.
JSON body: body*, targetLat*, targetLon*, targetHeight*, targetHeightRef, region* (GeoJSON Polygon | MultiPolygon | Feature, or bbox [west, south, east, north]), height, heightRef, start*, end*, temperature, pressure, dut1, aim, include (sun, phase or sun,phase), minIlluminated, maxSunAltitude
Example: curl -X POST -H 'content-type: application/json' https://ephem.ivar.workers.dev/v1/alignment/search -d '{"body":"moon","targetLat":40.68925,"targetLon":-74.0445,"targetHeight":70,"targetHeightRef":"msl","region":[-73.9995,40.7,-73.993,40.706],"height":5,"heightRef":"msl","start":"2026-11-16T00:00:00Z","end":"2026-11-18T00:00:00Z","maxSunAltitude":-4}'
/v1/sightline
Does the line of sight to the landmark clear what is between us? The sight line's height above sea level against ground distance from an eye to a target (Earth curvature; straight and refracted with k = 0.13), and the clearance over obstacle points lat:lon:heightMsl.
Parameters: lat*, lon*, height, heightRef, targetLat*, targetLon*, targetHeight*, targetHeightRef, samples, obstacles
Example: /v1/sightline?lat=40.6935&lon=-74.0017&height=5&heightRef=msl&targetLat=40.68925&targetLon=-74.0445&targetHeight=70&targetHeightRef=msl&samples=11&obstacles=40.6894:-74.0166:25
/v1/magnetic
What is the magnetic declination here? WMM2025 declination (turn the true azimuths above into compass bearings), inclination and intensity.
Parameters: lat*, lon*, height, heightRef, time
Example: /v1/magnetic?lat=40.7&lon=-74
/v1/weather
What is the weather at the nearest stations? Nearest METAR stations, decoded, with distance and true / magnetic bearing (temperature and pressure are the refraction inputs).
Parameters: lat*, lon*, count
Example: /v1/weather?lat=40.7&lon=-74&count=2
/healthz
Is it up? Liveness.
Parameters: none
Example: /healthz

Parameters

The same name means the same thing on every endpoint.

lat
Observer latitude, degrees north, −90 to 90 (WGS-84).
lon
Observer longitude, degrees east, −180 to 180 (WGS-84).
height
Observer height, metres (−500 to 100 000), measured from heightRef. Omitted: you stand at sea level (on the geoid).
heightRef
What the height is measured from: ellipsoid (default; WGS-84, as GPS reports) or msl (mean sea level, the EGM96 geoid; as maps and iOS altitude report).
targetLat
Target (landmark) latitude, degrees north, −90 to 90.
targetLon
Target (landmark) longitude, degrees east, −180 to 180.
targetHeight
Height of the point to frame (e.g. a torch or a tower top), metres (−500 to 100 000), measured from targetHeightRef.
targetHeightRef
What targetHeight is measured from: ellipsoid (default) or msl (EGM96, mean sea level).
body
sun or moon.
time
UTC instant, ISO-8601 with a trailing Z (e.g. 2026-11-17T03:45:00Z), 1972-01-01 to 2149-12-31. Default: now.
start
Window start, UTC ISO-8601 with a trailing Z (e.g. 2026-11-16T00:00:00Z).
end
Window end, UTC ISO-8601 with a trailing Z, after start.
date
Local calendar date, YYYY-MM-DD (with tz).
tz
IANA time zone, e.g. America/New_York; the day runs local midnight to local midnight.
stepSeconds
Sampling step, seconds.
temperature
Air temperature for refraction, °C (−90 to 60). Default 10.
pressure
Air pressure for refraction, hPa (0 to 1100). Default 1010.
horizon
Where the horizon is: sea (default: the sea horizon, dipped by your height above sea level), geometric (0°), or an apparent altitude in degrees (−1.6963 to 89).
horizonProfile
Skyline as azimuth:elevation pairs, comma-separated (degrees true : apparent degrees, as measured), e.g. 0:1.2,90:0.4,180:2.5,270:0.8; 1–360 points, linear in azimuth with wraparound, elevations ≥ −1.6963. Replaces horizon.
dut1
UT1 − UTC, seconds (−0.9 to 0.9). Default 0.
aim
Which point of the disc: center, upper or lower (the limbs along the local vertical), or litCentroid (the centroid of the Moon's lit area; body=moon).
include
Extra context per result: sun (the Sun's azimuth and true / apparent altitude there and then), phase (the Moon's phase), or sun,phase.
altitude
Altitude to cross, degrees (−90 to 90); true unless altitudeType=apparent. Required unless horizonProfile.
altitudeType
true (default: vacuum altitude, as twilight thresholds are defined) or apparent (refracted, as /v1/position's apparentAltitude).
direction
rise (upward crossings), set (downward) or either (default).
maxDistanceKm
Farthest standing point to report, km (0.01 to 200). Default 20.
samples
Points along the sight line, 2 to 1001. Default 101.
obstacles
Obstacle points lat:lon:heightMsl, comma-separated (up to 100; heights in metres above sea level), e.g. 40.6894:-74.0166:25. Each gets its clearance below the line.
count
How many stations, nearest first, 1 to 10. Default 1.
region
Where you can stand: a GeoJSON Polygon or MultiPolygon (holes allowed; or a Feature wrapping one), or a bbox [west, south, east, north]. At most 1 000 vertices, ≤ 50 km across, ≤ 100 km from the target and not containing it.
minIlluminated
Keep only passes with the Moon at least this illuminated, 0 to 1.
maxSunAltitude
Keep only passes with the Sun's true altitude at most this, degrees (e.g. −4 for a dark sky, −6 for after civil dusk).

Conventions

frame
Apparent, topocentric, true equator and equinox of date (light-time, annual + diurnal aberration, precession, nutation).
trueAltitude
Direction in vacuum: no atmospheric refraction.
apparentAltitude
The fixed point a = trueAltitude + R(a) with the one refraction model used by every endpoint: R(a) = 34′·(P/1010)·(283/(273 + T))·cot(a + 7.31/(a + 4.4))/cot(7.31/4.4), i.e. Bennett's (1982) shape normalised to the almanac's 34′ at the horizon (0.98685 × Skyfield's Bennett at every altitude); R = 0 above 89.9°. Defaults T = 10 °C, P = 1010 hPa. Applied down to the observer's horizon (`horizon`, default the sea horizon −dip) but never below −1.6963°, where Bennett's shape peaks; below that, apparentAltitude is null (CHANGED 2026-10-29: it used to repeat the true altitude below −1°, and used Skyfield's unnormalised Bennett, 0.45′ more at 0°). Below 0° the model is an extrapolation: against a US Standard Atmosphere 1976 ray trace it reads 0.1′ high at the sea horizon from 10 m, 1.0′ from 320 m, 2.6′ from 1 000 m, and the real atmosphere near the horizon varies far more than that with the weather.
height
`height` is metres above the WGS-84 ellipsoid by default; heightRef=msl makes it metres above the EGM96 geoid (≈ mean sea level). Without a height the observer stands on the geoid. Responses give heightEllipsoid, heightMsl and geoidUndulation N (heightEllipsoid = heightMsl + N; EGM96 from NGA's 15′ grid sampled at 30′, bilinear, rms 0.12 m / max 3.5 m interpolation error).
rise
The aim point (aim: upper limb by default, center, lower) at apparent altitude H, the horizon: H = −dip of the sea horizon for heightMsl (default), 0 (horizon=geometric), a given angle, or a profile by azimuth. Dip = √(1 − k)·acos(R/(R + heightMsl)), k = 0.13 (as /v1/alignment), R = 6 371 008.8 m (≈ 1.80′·√h). True limb altitude at rise/set = H − R(H), R the same refraction model as apparentAltitude (34′ at 0° with defaults, so sea level with defaults is the old −34′ − radius exactly). /v1/crossing at apparent altitude H, upper limb, gives the same instants (≤ 1 ms). Every response's conventions.riseSet gives the numbers used.
crossing
/v1/crossing: every instant in the window when the aim point (default the centre) reaches `altitude`, true (default) or apparent (the same refraction model as /v1/position and /v1/day), or meets a horizonProfile; rise = upward.
alignment
Standing point P solves: body azimuth at P = forward geodesic azimuth P→target, and body apparent altitude at P = target apparent elevation = geometric elevation (exact, WGS-84 ECEF) + k·θ/2 with k = 0.13, θ = geodesic distance / 6 371 008.8 m. Track points are omitted when the body is below −1° or no P lies within maxDistanceKm. Geodesics: WGS-84 (Vincenty/Karney agree to 1 mm here). Heights: height (the eye, heightRef) and targetHeight (targetHeightRef) are above the ellipsoid by default, above the EGM96 geoid with msl; no height = the eye on the geoid. Every response carries a conventions block (terrestrial refraction, azimuth, refraction, heights, rates).
aim
aim: which point of the disc. /v1/day: upper (default), center, lower. /v1/crossing, /v1/alignment, /v1/alignment/search: center (default), upper / lower = the limb along the local vertical (topocentric angular radius, asin(1737.4 km / topocentric distance), so parallax is included); litCentroid = the centroid of the Moon's illuminated area: (4r/3π)·(1 − cos i) from the centre towards the bright limb, i the topocentric phase angle, r the angular radius (orthographic disc, parallel sunlight). Offsets are applied in the true sky and the aim point's altitude is then refracted.
passes
/v1/alignment with lat/lon (a fixed spot): instants when the body's azimuth equals the azimuth to the target (±180° wraps excluded); altitudeOffset tells whether it is above (+) or behind (−) the target top.
rates
altitudeRate, azimuthRate: degrees per minute, analytic (DE440 Chebyshev velocity through light time, aberration and Earth rotation; no finite difference).
brightLimb
Position angle of the Moon's bright limb, measured from celestial north through east (Meeus 48.5), geocentric (phase.brightLimbAngle). moon.brightLimbAngleFromVertical is the same limb seen from the observer, degrees clockwise from the local vertical (towards increasing azimuth).
phase
Geocentric: phase angle Sun–Moon–Earth, illuminated fraction (1 + cos i)/2, elongation = λ☾ − λ☉ in [0, 360).
twilight
Sun centre true altitude crosses −6° (civil), −12° (nautical), −18° (astronomical). Not affected by height, horizon or refraction.
goldenHour
Sun centre true altitude between −4° and +6°.
blueHour
Sun centre true altitude between −6° and −4°.
track
/v1/track: the Sun's and Moon's azimuth, true altitude and apparent altitude at every point of a UTC grid (start, end on multiples of stepSeconds since 1970-01-01T00:00Z), columnar; each sample equals /v1/position's values at that instant bit for bit. Bounded: stepSeconds 60–3600, at most 8 days and 1 441 samples.
sightline
/v1/sightline: the sight line's height above sea level against ground distance from an eye to a target (straight chord between WGS-84 ECEF points, so Earth's curvature is included; and the refracted ray with k = 0.13, which runs k·s₁·s₂/(2R) higher), plus each obstacle point's clearance. Terrestrial refraction is modelled as that constant coefficient only.
search
POST /v1/alignment/search (JSON body): every pass in [start, end) (≤ 400 days) when the alignment standing point lies inside a region (GeoJSON Polygon / MultiPolygon with holes, or bbox [w, s, e, n]); segments with exact entry / exit (solved on the track to 1 mm), the body's azimuth / apparent altitude / angular radius, the Moon's illuminatedFraction and the Sun's sunAltitude per pass; filters minIlluminated, maxSunAltitude; include sun, phase; aim. Candidates come from the target's elevation and bearing band over the whole region (no representative elevation), scanned with proven rate bounds. Computed per 30-day window, each an immutable cached unit, so overlapping scans share work.
supportedRange
1972-01-01T00:00:00Z to 2149-12-31T23:59:59Z (UTC with leap seconds; DE440 coverage).
ut1
UT1 = UTC + dut1 (request parameter, default 0). No polar motion.
magnetic
WMM2025 (NOAA NCEI), degree 12 with secular variation; declination east positive; magnetic bearing = true − declination. Verified against the model's published test values.
weather
Nearest METAR stations by great-circle distance from aviationweather.gov's all-stations feed, cached ≤ 60 s fresh, served up to 10 min stale while it refreshes; feed.tier and feed.ageSeconds say which.
unknownParameters
Every endpoint rejects parameters (and POST body fields) it does not define with 400 InvalidRequest, naming them, suggesting the intended one (renamed or misspelled) and listing the allowed ones.