Ephemerides API
Sun and moon data for any location on Earth: rise and set times, twilight phases, transit times, moon phase and illumination. Positions come from JPL DE421 and are accurate to under an arcsecond. Rise, set and twilight times are accurate to about a minute for dates from 1900 to 2050. See the methodology.
How this differs from other ephemerides APIs
Other ephemerides APIs compute rise and set times at sea level, even when the observer is on a mountain. We take the observer's elevation (or look it up for you) and apply the geometric horizon-dip correction. At 4 000 m, sunrise comes roughly 8 to 14 minutes earlier than at sea level, depending on latitude and season, and the times we return reflect that. It matters for mountain photography, solar siting, mountaineering and 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 defaults to 5 years (1825 days), and we can raise it 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 | The five daily Islamic prayer times, with a choice of school and 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]. Rises come earlier and sets later 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 the sun never crossed that boundary during the local day. This is normal at high latitudes: in Dublin, for example, astronomical twilight does not occur from mid-May to late July.
Accuracy notes
Rise, set and transit times are normally accurate to within a minute. When another source differs by more than that, the cause is usually a different horizon convention, or local terrain that global models don't capture.
- 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.