API
A free JSON API is planned, and this page describes what it will return. It is not live yet — the endpoints below do not answer.
Status
Not available yet. There is no waiting list and nothing to sign up for; when the endpoints go live this page becomes the documentation.
Until then, every value the API will return is already on the city pages in
readable form, and each page links to its own future JSON endpoint through a
<link rel="alternate" type="application/json"> tag.
What it will return
The same values the pages are built from: sunrise and sunset, all three twilights, solar noon, maximum sun altitude, morning and evening golden hour, both blue hours, sunrise and sunset azimuth with compass labels, day and night length, the change since yesterday, and moonrise, moonset, phase and illumination.
Polar days will be reported honestly rather than as nulls: a field saying the sun does not set, with the date range that holds for.
Planned endpoints
| Endpoint | Returns |
|---|---|
/api/v1/sun | Everything above for a latitude, longitude and date |
/api/v1/city/{id} | The same, for a tracked city by GeoNames id |
/api/v1/status | Service health and the current data version |
Terms it will carry
Free to use with attribution: a visible link back to this site on any page or screen showing the data. Rate limited per IP, with a documented limit and a JSON error rather than a silent drop. Responses cached for an hour.