Ephemerides API
High-precision sun and moon data for any location on Earth: rise / set times, twilight phases, transit times, moon phase and illumination. Positions from JPL DE421 (sub-arcsecond); rise / set & twilight times accurate to about a minute, 1900–2050. See methodology.
⛰️ Why thirdtrail vs. other ephemerides APIs?
Every other API on the market computes rise/set times at sea level, even if your observer is on a mountain. We accept (and optionally auto-derive) the observer's elevation and apply the geometric horizon-dip correction, so your sunrise time at 4 000 m is genuinely 17 minutes earlier than at sea level — not just a copied value. Indispensable for mountain photography, solar siting, mountaineering, and scientific observation at altitude.
Endpoint: GET /v1/ephemerides/ ·
Auth: API key (Authorization: Bearer tt_live_…)
⚠️ Informational use only — not for navigation or safety-of-life decisions. These sun, moon and twilight times are computed for convenience and are elevation-corrected, so they deliberately differ from the standard, level-horizon civil-twilight times that aviation and maritime regulators require. Do not use them for flight planning, to determine legal day/night or “lights-on” times, for navigation, or for any other safety-of-life purpose. Always verify against an official source. Safe use & disclaimers →
Quick start
curl -H "Authorization: Bearer $THIRDTRAIL_KEY" \
"https://thirdtrail.life/v1/ephemerides/?lat=53.349&lon=-6.260&days=7"Tier matrix
| Feature | Free | Starter €9 | Pro €39 | Business €149 | Enterprise |
|---|---|---|---|---|---|
| Calls per day | 100 | 2,000 | 25,000 | 250,000 | custom |
| Burst per minute | 10 | 30 | 120 | 600 | unlimited |
| Max forecast days | 7 | 30 | 90 | 365 | 1825¹ |
| Sun & moon rise / set | ✅ | ✅ | ✅ | ✅ | ✅ |
| Moon phase + illumination | ✅ | ✅ | ✅ | ✅ | ✅ |
| Twilight (civil / nautical / astronomical) | — | ✅ | ✅ | ✅ | ✅ |
| Zenith / transit times | — | ✅ | ✅ | ✅ | ✅ |
| Golden / blue hour windows | — | ✅ | ✅ | ✅ | ✅ |
iCal feed (feed.ics) | — | ✅ | ✅ | ✅ | ✅ |
| Prayer-times endpoint | — | ✅ | ✅ | ✅ | ✅ |
Bulk endpoint (/bulk) | — | — | ✅ (100/req) | ✅ (1k/req) | ✅ (5k/req) |
| Webhooks (event subscriptions) | — | — | ✅ | ✅ | ✅ |
| Historical queries | — | ✅ | ✅ | ✅ | ✅ |
| Localised phase names | — | — | ✅ | ✅ | ✅ |
auto_elevation & auto_timezone | — | — | — | ✅ | ✅ |
¹ Enterprise default is 5 years (1825 days), raisable per customer.
Endpoints at a glance
| Endpoint | Method | Purpose |
|---|---|---|
/v1/ephemerides/ | GET | Multi-day sun & moon events for one location. |
/v1/ephemerides/prayer-times/ | GET | Five Islamic prayer times. Selectable school + Asr method (Starter+). |
/v1/ephemerides/bulk/ | POST | Up to 5 000 location/date tuples in one request (Pro+). |
/v1/ephemerides/feed.ics | GET | Calendar subscription (Apple Calendar / Google Calendar / Outlook). |
/v1/ephemerides/webhooks/ | POST / GET / DELETE | Event subscriptions. Webhooks docs → |
Query parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
lat | float | yes | — | Latitude, decimal degrees, [-90, 90] |
lon | float | yes | — | Longitude, decimal degrees, [-180, 180] |
elevation | float | no | 0 | Metres above sea level. [-500, 9000]. Earlier rises / later sets at altitude. |
days | int | no | plan-dependent | Capped by your plan's max forecast days. |
start_date | date | no | today (UTC) | YYYY-MM-DD. Past dates require a paid plan. |
tz | string | no | — | IANA timezone name, e.g. Europe/Dublin. |
utc_offset | string | no | — | Fixed offset ±HH:MM or Z. No DST. |
auto_timezone | bool | no | false | Business+. Resolves timezone from lat / lon. |
auto_elevation | bool | no | false | Business+. Resolves elevation from lat / lon. |
lang | string | no | en | Pro+. en / fr / es / de / it / pt. |
When no timezone parameter is supplied, all times are returned in UTC, ISO-8601 with a Z suffix
(e.g. 2026-05-19T04:21:22Z). The actual timezone used is always echoed back in resolved.timezone.
Example response
{
"request": { "lat": 53.349, "lon": -6.260, "days": 7, ... },
"resolved": { "elevation_m": 0, "elevation_source": "default",
"timezone": "UTC", "timezone_source": "default",
"plan": "free" },
"timezone": "UTC",
"days": [
{
"date": "2026-05-19",
"sun": { "rise": "2026-05-19T04:21:14Z", "set": "2026-05-19T20:42:33Z", "status": "ok" },
"moon": { "rise": "2026-05-19T05:49:34Z", "set": "2026-05-19T23:32:56Z",
"status": "ok",
"phase": { "angle_deg": 37.3, "illumination": 0.10, "name": "Waxing Crescent" } }
}
],
"compute_ms": 87
}Twilight conventions
- Civil: sun centre at -0.83° to -6°. Streetlights typically off; bright stars visible.
- Nautical: -6° to -12°. Horizon distinguishable; navigation by stars feasible.
- Astronomical: -12° to -18°. Faint celestial objects observable.
A null twilight value means that boundary was not crossed during the local day — this is normal at high latitudes (e.g. astronomical twilight does not occur in Dublin from mid-May to late July).
Accuracy notes
Rise / set / transit times are normally accurate to within 1 minute. Larger discrepancies vs. external sources are usually due to differing horizon conventions or local terrain not captured by global models.
- Atmospheric refraction: standard 34′ depression applied.
- Elevation correction: geometric horizon dip computed from observer altitude.
- Auto-elevation: global terrain grid, ~9 km horizontal resolution.
- Polar edge cases reported via the
statusfield (ok/always_up/always_down).
These times use the standard horizon convention adjusted for your elevation, so they are not the official, level-horizon civil-twilight times that aviation and maritime regulators require. Do not use them for legal day/night, navigation or flight planning — see Safe use and methodology.