Twilight times API
Twilight is defined by the Sun's depression below the horizon: 6 degrees for civil, 12 for nautical, 18 for astronomical. Give a place and a date; get each dawn and dusk in local and UTC time, and an explicit answer when the Sun never gets that low (summer at high latitudes).
Get a free key Try it in the playground API reference
What you get
- Civil, nautical and astronomical dawn and dusk
- Blue hour, morning and evening (day route)
- The night window used for observing (visibility route)
- null with a stated reason when a twilight does not happen that day
Example
curl -X POST https://astro-agent.dev/v1/astronomy/rise-set -H 'Content-Type: application/json' \
-H "X-Credits-Token: $ASTRO_AGENTS_KEY" -d '{"date":"2026-12-21","latitude":59.3293,"longitude":18.0686}'
A real answer to this request (excerpt). The same request always returns the same
result_sha256, which POST https://astro-agent.dev/v1/verify recomputes for free:
{
"endpoint": "astronomy/rise-set",
"result": {
"sun": {
"astronomical_dawn": "2026-12-21T06:01:52+01:00",
"nautical_dawn": "2026-12-21T06:52:19+01:00",
"civil_dawn": "2026-12-21T07:47:43+01:00",
"civil_dusk": "2026-12-21T15:43:48+01:00",
"nautical_dusk": "2026-12-21T16:39:12+01:00",
"astronomical_dusk": "2026-12-21T17:29:39+01:00"
}
},
"meta": {
"result_sha256": "450ffd67fe6f6e96f7a580ce2490f8d19af50ac58e7cf21f5b5fee6dd013227f"
}
}
Routes and prices
| Route | Name | Price per call | What it returns |
|---|---|---|---|
POST /v1/astronomy/rise-set | Rise, set and twilight times for a place | $0.01 | Rise, transit and set of the Sun, Moon and planets for a place and local day, with civil, nautical and astronomical twilight, day length, golden hour and blue hour. |
POST /v1/astronomy/day | Astronomical summary of the day for a place | $0.02 | One call for a day at a place: sunrise, sunset, twilight, day length, golden and blue hour; the Moon's phase, illumination, rise and set; the planets observable that night; the next lunations, planetary stations and eclipse. |
The same routes are MCP tools on https://astro-agent.dev/mcp.
Limits
- Dates from 1800 to 2200; range routes take up to a year per call.
- Without a key: 1 free call on the $0.01-0.02 routes, then HTTP 402 with a pay-per-call offer (USDC, x402).
- Free key (an email, no card): 10,000 calls a month, 30 a minute, personal, research and evaluation use only. Paid plans from $19 a month by card, for commercial use: see pricing.
- Past the quota, calls answer 429 until the 1st of the month: nothing is charged beyond the plan.
Alternatives
sunrise-sunset.org returns the three twilights free, with an attribution link. For today's values in a simple app, it is enough.
Checked on the providers' own pages on 2026-11-20. Their terms may have changed since.
When Astro Agents fits
- Aviation, maritime and photography tools that need the definitions stated in the result
- Historical dates with their time zone
- Twilight alongside the Moon and planets in one call