# ephem > The Sun and Moon from JPL DE440, as a JSON HTTP API and an MCP server: where they are, what they do on a day, when they reach an altitude, and where to stand so one sits on a landmark. 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 its conventions. ## Start here - 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' ## Machine-readable - OpenAPI 3.1: https://ephem.ivar.workers.dev/openapi.json - MCP (Streamable HTTP, no auth): https://ephem.ivar.workers.dev/mcp (one tool per endpoint, same names: position, track, day, crossing, alignment, alignment_search, sightline, magnetic, weather; each takes the same arguments and returns the same JSON) - Human docs (plain HTML): https://ephem.ivar.workers.dev/docs - Page for people: https://ephem.ivar.workers.dev/ (live sky; ?lat&lon&tz override the location) ## Rules - Times are UTC ISO-8601 with a trailing Z (e.g. 2026-11-17T03:45:00Z); supported 1972-01-01 to 2149-12-31. - Angles are degrees; azimuth from true north through east, [0, 360). Rates are degrees per minute. - Heights are metres above the WGS-84 ellipsoid unless heightRef=msl (targetHeightRef=msl for an alignment target); without a height the observer is on the EGM96 geoid (sea level). - Errors are JSON {_tag, message, parameter?, allowed?}: 400 InvalidRequest for anything wrong with the request (unknown, missing, malformed or out-of-range parameter, or an impossible combination; the message names the parameter, what was wrong and what is allowed); 503 Unavailable when a data source (geoid, METAR feed) fails; 404 NotFound lists the endpoints. - Every response has conventions (every threshold, model, refraction input and height reference it used) and provenance (implementation, version, sources; blocks, compute time and cache tiers where it computed). - One vocabulary everywhere: lat, lon, height, heightRef (you); targetLat, targetLon, targetHeight, targetHeightRef (the landmark); body; time, start, end, date, tz, stepSeconds; temperature, pressure, horizon, horizonProfile, dut1; aim; include. Every endpoint is under /v1, which changes in place until it is declared stable. - Deterministic answers (anything with an explicit time or window) are cached immutably; x-ephem-cache says HIT or MISS. ## 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). params: lat*, lon*, height, heightRef, time, temperature, pressure, horizon, dut1 example: https://ephem.ivar.workers.dev/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. params: lat*, lon*, height, heightRef, start*, end*, stepSeconds, temperature, pressure, horizon, dut1 example: https://ephem.ivar.workers.dev/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). params: lat*, lon*, height, heightRef, date*, tz*, temperature, pressure, horizon, horizonProfile, aim, dut1 example: https://ephem.ivar.workers.dev/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. params: lat*, lon*, height, heightRef, body*, altitude, altitudeType, horizonProfile, direction, start, end, date, tz, temperature, pressure, dut1, include, aim example: https://ephem.ivar.workers.dev/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. params: body*, targetLat*, targetLon*, targetHeight*, targetHeightRef, height, heightRef, start*, end*, stepSeconds, maxDistanceKm, temperature, pressure, dut1, lat, lon, include, aim example: 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 - 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. fields: 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. params: lat*, lon*, height, heightRef, targetLat*, targetLon*, targetHeight*, targetHeightRef, samples, obstacles example: https://ephem.ivar.workers.dev/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. params: lat*, lon*, height, heightRef, time example: https://ephem.ivar.workers.dev/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). params: lat*, lon*, count example: https://ephem.ivar.workers.dev/v1/weather?lat=40.7&lon=-74&count=2 - /healthz: Is it up? Liveness. params: none example: https://ephem.ivar.workers.dev/healthz ## Parameters (the same meaning 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.