Docs / Sun, moon and satellites / Sunrise and sunset times

Sunrise and sunset times

Sunrise, sunset, solar noon, day length and the three twilights for a place and a date, in the timezone you choose.

curl "https://agent-helper.org/sky/sun?point=55.7558,37.6173&tz=Europe/Moscow&date=2026-09-15"
sunrise 2026-09-15T06:01:16+03:00
sunset 2026-09-15T18:47:06+03:00
noon 2026-09-15T12:24:56+03:00
day-length PT12H45M49S
civil-dawn 2026-09-15T05:23:07+03:00
civil-dusk 2026-09-15T19:25:05+03:00
nautical-dawn 2026-09-15T04:38:00+03:00
nautical-dusk 2026-09-15T20:09:55+03:00
astronomical-dawn 2026-09-15T03:48:48+03:00
astronomical-dusk 2026-09-15T20:58:40+03:00
# type: computed
# location: 55.7558,37.6173
# date: 2026-09-15
# timezone: Europe/Moscow (MSK, UTC+03:00, standard time)
# method: NOAA solar equations (astral), standard refraction 34' and solar radius 16', accuracy about 1 minute
# tzdata: 2026d
# note: for sea level with a flat horizon; mountains and elevation shift the times

The trap

Sunrise and sunset are local events, yet the calculation happens in whatever timezone the code happens to use, and the classic result is a sunset that looks impossible.

Take New York on 21 June. The sun rises at about 05:25 local time and sets at about 20:30. The same instants in UTC are 09:25, and 00:30 on 22 June. A service that answers in UTC for the date 21 June has to decide which UTC day it means, and a sunset at 00:30 on 21 June UTC is the sunset of 20 June in New York. Put the two values side by side and the day seems to end before it begins. People who see this report the data as broken; programs compute a negative day length, or quietly add a day and carry an error of one day forward.

There are two halves to the mistake. One is the date: 21 June is a calendar day at the place, and it lines up with the UTC day only near the prime meridian. The other is presentation: a time without an offset, or with a Z the reader skims past, gets read as local time.

Latitude brings days that simple code does not expect. North of the Arctic Circle there is no sunset in midsummer and no sunrise in midwinter. Further south, there are summer nights on which the sun never sinks far enough for nautical or astronomical twilight to end, as in Moscow in June. Code that expects every field to hold a time fails on those days or fills them with nonsense.

Published times also assume a flat horizon at sea level with standard atmospheric refraction. A valley, a ridge or a tall building shifts what an observer actually sees by minutes, and no calculation from coordinates alone accounts for that.

What this endpoint does

A timezone is required: tz= takes an IANA name, and the date is the calendar day in that zone. UTC is accepted when named and never assumed. Every time carries its offset. When the zone does not match the place, so that the listed sunset comes before the listed sunrise, a note says so instead of leaving the order to look like an error.

Days without a sunrise or sunset are answered with none and the reason, polar day or polar night, and twilights that do not end are marked the same way. The calculation uses the NOAA solar equations with standard refraction for a flat horizon at sea level, and the answer states that elevation and terrain are not taken into account. event= returns a single value.

Parameters

NameRequiredMeaning and valuesDefaultLimit
pointyeslatitude,longitude in decimal degrees—60 characters
tzyesIANA timezone for the output; required because 'the date' and the times depend on it—1024 bytes
datenolocal date YYYY-MM-DD (default: today in tz)—40 characters
eventnoreturn one value only
one of sunrise, sunset, noon, civil-dawn, civil-dusk, nautical-dawn, nautical-dusk, astronomical-dawn, astronomical-dusk, day-length		—1024 bytes

The whole path and query together are capped at 2048 bytes. Every parameter has the same meaning under /v1/sky/sun.

Examples

New York in UTC: sunset listed before sunrise

curl "https://agent-helper.org/sky/sun?point=40.7128,-74.0060&tz=UTC&date=2026-06-21"
sunrise 2026-06-21T09:25:17Z
sunset 2026-06-21T00:30:16Z
noon 2026-06-21T16:57:44Z
day-length PT15H4M59S
civil-dawn 2026-06-21T08:51:13Z
civil-dusk 2026-06-21T01:04:20Z
nautical-dawn 2026-06-21T08:08:42Z
nautical-dusk 2026-06-21T01:46:51Z
astronomical-dawn 2026-06-21T07:18:20Z
astronomical-dusk 2026-06-21T02:37:14Z
# type: computed
# location: 40.7128,-74.006
# date: 2026-06-21
# timezone: UTC (UTC, UTC+00:00, standard time)
# method: NOAA solar equations (astral), standard refraction 34' and solar radius 16', accuracy about 1 minute
# tzdata: 2026d
# note: sunset is earlier than sunrise: in UTC, 2026-06-21 contains the sunrise of that morning and the sunset of the evening before, as seen at this place; the place's own timezone gives the order people expect, and day-length is approximated from these two times
# note: for sea level with a flat horizon; mountains and elevation shift the times

The same day in New York time

curl "https://agent-helper.org/sky/sun?point=40.7128,-74.0060&tz=America/New_York&date=2026-06-21"
sunrise 2026-06-21T05:25:17-04:00
sunset 2026-06-21T20:30:29-04:00
noon 2026-06-21T12:57:44-04:00
day-length PT15H5M12S
civil-dawn 2026-06-21T04:51:13-04:00
civil-dusk 2026-06-21T21:04:33-04:00
nautical-dawn 2026-06-21T04:08:42-04:00
nautical-dusk 2026-06-21T21:47:03-04:00
astronomical-dawn 2026-06-21T03:18:20-04:00
astronomical-dusk 2026-06-21T22:37:26-04:00
# type: computed
# location: 40.7128,-74.006
# date: 2026-06-21
# timezone: America/New_York (EDT, UTC-04:00, daylight saving time in effect)
# method: NOAA solar equations (astral), standard refraction 34' and solar radius 16', accuracy about 1 minute
# tzdata: 2026d
# note: for sea level with a flat horizon; mountains and elevation shift the times

Midsummer in Tromsø: no sunset

curl "https://agent-helper.org/sky/sun?point=69.6492,18.9553&tz=Europe/Oslo&date=2026-06-21"
sunrise none (polar day: the sun stays above the horizon)
sunset none (polar day: the sun stays above the horizon)
noon 2026-06-21T12:45:53+02:00
day-length P1D
civil-dawn none (the sun does not reach that depression)
civil-dusk none (the sun does not reach that depression)
nautical-dawn none (the sun does not reach that depression)
nautical-dusk none (the sun does not reach that depression)
astronomical-dawn none (the sun does not reach that depression)
astronomical-dusk none (the sun does not reach that depression)
# type: computed
# location: 69.6492,18.9553
# date: 2026-06-21
# timezone: Europe/Oslo (CEST, UTC+02:00, daylight saving time in effect)
# method: NOAA solar equations (astral), standard refraction 34' and solar radius 16', accuracy about 1 minute
# tzdata: 2026d
# note: for sea level with a flat horizon; mountains and elevation shift the times

No timezone given (error)

curl "https://agent-helper.org/sky/sun?point=40.7128,-74.0060&date=2026-06-21"
error: 400 bad parameter 'tz'
parameter: tz
problem: required parameter is missing (IANA timezone for the output; required because 'the date' and the times depend on it)
hint: sunrise and sunset are reported in the local time of a zone, and 'the date' depends on it; UTC is never assumed (tz=UTC is accepted)
example: /sky/sun?point=55.7558,37.6173&tz=Europe/Moscow&date=2026-09-15
[the rest of this error repeats the parameter list above]

Limits and provenance

Rate class light (light computations: conversion, validation, dates, encodings, text, networks, geometry): 120 requests a minute per address, bursts of 30; wider limits apply per network and per autonomous system. Current values: /limits.

Answers are marked # type: computed; successful ones are served with Cache-Control: public, max-age=86400.

Computed locally; no external data source is involved.

Related