Twilight band transition times (night → civil → nautical → astronomical) over a date range.

---

Overview

Returns the transitions between twilight bands over a specified date range as observed from a given location. The twilight bands — civil, nautical, and astronomical — are defined by how far the Sun is below the horizon: civil twilight ends at -6°, nautical at -12°, and astronomical at -18°. Below -18° the sky is considered fully dark (night). The response includes the precise datetime of each transition and the band names on either side of the transition. Useful for photography planning, nautical scheduling, and astronomical observation windows.

---

Request parameters

Name	Type	In	Required	Description	Example
date1	Date	Body	Yes	The start date (or single query date) for the computation. Accepted formats: YYYY-MM-DD for date-only fields, ISO 8601 datetime string (YYYY-MM-DDTHH:MM) for datetime fields.
date2	Date	Body	Yes	The end date of the query range. Must be on or after date1. Accepted format: YYYY-MM-DD. The range is inclusive of both dates.
lat	Float	Body	Yes	Observer latitude in decimal degrees. Valid range: -90.0 (South Pole) to 90.0 (North Pole). Used to compute the observer's position on Earth's surface for all sky calculations.
lon	Float	Body	Yes	Observer longitude in decimal degrees. Valid range: -180.0 to 180.0. Negative values are west of the Prime Meridian, positive values are east.
timezone_slug	Choice	Body	Optional	Slug of a timezone record used to localise event datetimes in the response (e.g. america-new-york). When omitted, the timezone is derived automatically from the supplied coordinates. Obtain valid timezone slugs from the timezone list endpoint.

---

Response fields

Name	Type	Nullable	Description	Example
body	String	Yes	Skyfield key of the queried body, or null for fixed-body endpoints (sunrise, moonrise, twilight, seasons).	SUN
count	Integer	—	Number of events found within the requested date range.	30
date1	Datetime	—	Start of the query window echoed from the request.	2025-06-01T00:00:00
date2	Datetime	—	End of the query window echoed from the request.	2025-06-30T00:00:00
events	Array	—	List of discrete sky events ordered chronologically.
events[].date	String	—	Date formatted as abbreviated weekday and month (e.g. Sat Jun 21 2025).	Sat Jun 21 2025
events[].datetime	Datetime	—	Full datetime of the event in the observer's local timezone.	2025-06-21T06:14:00-07:00
events[].duration_days	Float	—	Days from this event until the next, rounded to one decimal place.	0.3
events[].duration_hours	Float	—	Hours from this event until the next, rounded to one decimal place.	8.2
events[].duration_minutes	Float	—	Minutes from this event until the next event in the sequence.	489.5
events[].duration_weeks	Float	—	Weeks from this event until the next, rounded to three decimal places.	0.048
events[].id	Integer	—	Sequential index of the event within the result set.	0
events[].literal_date	String	—	Date formatted as full month name and day (e.g. June 21).	June 21
events[].name	String	—	Human-readable label for the event type (e.g. Sunrise, Full Moon, Summer).	Sunrise
events[].naturalday	String	—	Human-relative day description (e.g. Today, Yesterday, Tomorrow).	Tomorrow
events[].naturaltime	String	—	Human-relative time description generated by Django humanize (e.g. 3 hours ago).	3 hours from now
events[].short_date	String	—	Date formatted as ISO 8601 (YYYY-MM-DD).	2025-06-21
events[].short_literal_date	String	—	Date formatted as abbreviated month name and day (e.g. Jun 21).	Jun 21
events[].symbol	String	—	Unicode symbol representing the event type (e.g. ☀ for sunrise, 🌑 for new moon).	☀
events[].time	String	—	Time of the event formatted as 12-hour clock with AM/PM (e.g. 06:14 am).	06:14 am
events[].type	Integer	—	Integer code identifying the event type within its category (0 = first variant, 1 = second, etc.).	1
lat	Float	—	Observer latitude echoed from the request.	48.428333
lon	Float	—	Observer longitude echoed from the request.	-123.364722
tz	String	—	Resolved IANA timezone name for the observer's location.	America/Vancouver