Daylight and Twilight Explained: Civil, Nautical, and Astronomical Twilight

July 22, 2026

Sunrise and sunset seem like clear dividing lines between day and night. In reality, the transition is gradual.

The sky begins to brighten well before sunrise and remains illuminated after the Sun has set. This period of indirect sunlight is known as twilight, and it is divided into three stages: civil twilight, nautical twilight, and astronomical twilight.

Each stage is defined by how far the center of the Sun is below the horizon. These definitions help describe how much natural light remains and are used in fields ranging from aviation and navigation to astronomy, photography, construction, and outdoor recreation.

What Is Daylight?

Daylight generally refers to the period between sunrise and sunset, when at least part of the Sun is above the horizon.

However, useful natural light does not begin exactly at sunrise or end exactly at sunset. The atmosphere scatters sunlight even when the Sun is below the horizon, producing the gradual brightening before sunrise and fading light after sunset.

This means there are several useful ways to describe the length of the day:

Daylight duration: The time between sunrise and sunset
Civil light duration: The time from the beginning of morning civil twilight until the end of evening civil twilight
Twilight duration: The transition period before sunrise or after sunset
Night: The period after astronomical twilight ends and before astronomical twilight begins

For many everyday activities, civil twilight may be more useful than sunrise and sunset alone because it better represents the period when outdoor light is still available.

Why Does Twilight Occur?

Twilight occurs because Earth’s atmosphere scatters sunlight.

When the Sun is just below the horizon, its light still passes through the upper atmosphere. Air molecules, dust, water droplets, and other particles scatter some of that light toward the ground.

As the Sun moves farther below the horizon, less sunlight reaches the atmosphere above the observer. The sky gradually becomes darker until direct scattered sunlight is no longer visible.

The duration and appearance of twilight vary depending on:

Latitude
Time of year
Atmospheric conditions
Elevation
The angle at which the Sun crosses the horizon

Near the equator, the Sun generally descends below the horizon at a relatively steep angle, so twilight is often short. At higher latitudes, the Sun may move across the horizon at a shallower angle, creating much longer twilight periods.

The Three Types of Twilight

Twilight is divided into three stages according to the Sun’s position below the horizon.

Twilight stage	Sun below the horizon	General conditions
Civil twilight	0° to 6°	Most outdoor activities remain possible without artificial light
Nautical twilight	6° to 12°	The horizon is still visible, but general outdoor visibility is limited
Astronomical twilight	12° to 18°	The sky is nearly dark, although faint scattered sunlight remains
Night	More than 18°	The Sun no longer contributes meaningful illumination to the sky

These angles refer to the geometric center of the Sun.

What Is Civil Twilight?

Civil twilight is the brightest stage of twilight. It occurs when the center of the Sun is between the horizon and 6 degrees below it.

Morning civil twilight begins when the Sun reaches 6 degrees below the horizon and ends at sunrise. Evening civil twilight begins at sunset and ends when the Sun reaches 6 degrees below the horizon.

During civil twilight, there is usually enough natural light for many normal outdoor activities. Large objects remain easy to distinguish, and the horizon is clearly visible.

Streetlights and vehicle headlights may begin to turn on during this period, but complete artificial illumination is not always necessary.

Civil twilight is particularly relevant for:

Outdoor work
Running and walking
Construction planning
Aviation
Photography
Parks and recreational facilities
Road safety
Solar-lighting systems

For most people, civil twilight provides the most practical definition of when usable daylight begins and ends.

Civil Dawn and Civil Dusk

The beginning of morning civil twilight is sometimes called civil dawn. The end of evening civil twilight is called civil dusk.

These are not the same as sunrise and sunset.

For example, civil dawn may occur 20 to 40 minutes before sunrise at many mid-latitude locations, while civil dusk may occur a similar amount of time after sunset. The exact difference varies by location and date.

What Is Nautical Twilight?

Nautical twilight occurs when the Sun is between 6 and 12 degrees below the horizon.

The term comes from traditional marine navigation. During nautical twilight, sailors could often see enough of the horizon to determine its position while also seeing bright stars used for celestial navigation.

During this stage:

The horizon may still be visible
Major outlines of the landscape may be distinguishable
Most outdoor activities require artificial light
Many brighter stars and planets become visible
The sky still contains noticeable illumination from the Sun

Morning nautical twilight begins when the Sun reaches 12 degrees below the horizon and ends when civil twilight begins. Evening nautical twilight begins after civil twilight and ends when astronomical twilight begins.

Although modern navigation relies heavily on GPS and electronic systems, nautical twilight remains a useful measure for marine operations, aviation, military planning, photography, and observational astronomy.

What Is Astronomical Twilight?

Astronomical twilight occurs when the Sun is between 12 and 18 degrees below the horizon.

At this stage, the sky appears dark to most observers, but a small amount of scattered sunlight may still interfere with observations of faint stars, galaxies, and other astronomical objects.

Astronomical twilight ends when the Sun reaches 18 degrees below the horizon. Beyond this point, the sky is considered fully dark from the standpoint of sunlight.

Astronomical twilight matters most for:

Professional astronomy
Astrophotography
Observatories
Dark-sky planning
Satellite observation
Viewing faint celestial objects

Bright planets and stars may be visible much earlier, during civil or nautical twilight. However, observing faint deep-sky objects usually requires the darker conditions found after astronomical twilight has ended.

Astronomical Dawn and Astronomical Dusk

Astronomical dawn occurs when the Sun rises to 18 degrees below the horizon in the morning and the sky begins to receive measurable scattered sunlight.

Astronomical dusk occurs when the Sun descends past 18 degrees below the horizon in the evening.

The period between astronomical dusk and astronomical dawn is commonly described as astronomical night.

Sunrise and Sunset Are Not Instantaneous

Sunrise and sunset are usually reported as specific times, but the Sun takes several minutes to move fully above or below the horizon.

Official sunrise is normally defined as the moment when the upper edge of the Sun appears at the horizon. Official sunset occurs when the upper edge disappears below it.

These calculated times also account for atmospheric refraction, which bends sunlight and makes the Sun appear slightly higher than its true geometric position.

As a result, sunrise may be reported before the Sun’s geometric center has actually crossed the horizon, and sunset may be reported after it has geometrically moved below it.

Local terrain can create additional differences. Mountains, buildings, trees, and other obstructions may block the visible Sun even though the calculated sunrise or sunset has already occurred.

How Long Does Twilight Last?

There is no single fixed twilight duration.

At many locations in the continental United States, each stage of twilight may last roughly 20 to 40 minutes. However, this is only a general guide.

Twilight duration depends primarily on latitude and season.

Near the Equator

Near the equator, the Sun usually crosses the horizon at a steep angle. It therefore moves through the twilight zones relatively quickly.

The transition from daylight to darkness can feel rapid.

At Mid-Latitudes

At mid-latitudes, twilight changes noticeably through the year. It is generally shorter near the equinoxes and longer around the summer solstice.

Near the Poles

At high latitudes, the Sun may move almost parallel to the horizon. Twilight can last for hours or continue throughout the night.

In some locations, the Sun does not descend 18 degrees below the horizon during parts of summer. This means astronomical night never occurs.

Farther north or south, the Sun may remain above the horizon entirely, producing the midnight Sun. During winter, the opposite can occur, with the Sun remaining below the horizon for days or months.

Why Twilight Times Matter

Sunrise and sunset data are commonly used in weather applications, but twilight times can provide a more realistic picture of available natural light.

Outdoor Activities

Hikers, runners, cyclists, boaters, golfers, and other outdoor users may need to know when visibility will become limited rather than simply when sunset occurs.

Civil dusk often gives a better estimate of when artificial lighting becomes necessary.

Construction and Field Operations

Construction, agriculture, surveying, inspections, and utility work frequently depend on usable daylight.

Planning around civil twilight can provide a more practical working window than sunrise-to-sunset duration alone.

Aviation

Twilight definitions are used in aviation planning and regulations, although specific legal definitions and operating rules may vary by jurisdiction.

Pilots may also need to consider visibility, terrain, weather, and airport-lighting conditions rather than relying solely on calculated twilight times.

Marine Navigation

Nautical twilight historically provided the ideal balance between a visible horizon and visible navigation stars.

It remains useful for planning marine departures, arrivals, and low-light operations.

Astronomy and Astrophotography

Astronomical twilight helps observers determine when the sky will become dark enough for faint-object viewing.

Moonlight, clouds, haze, smoke, and artificial light pollution can still affect viewing conditions even after astronomical twilight has ended.

Photography

Photographers often plan around civil and nautical twilight because these periods can provide softer light and a more balanced contrast between the sky and landscape.

The period shortly after sunset or before sunrise is often called the blue hour, although it does not have a single formal astronomical definition and may not last a full hour.

Twilight Is Different From the Golden Hour

Twilight is defined by the Sun’s position below the horizon.

The golden hour, by contrast, is an informal photography term describing the warm, low-angle sunlight that often occurs shortly after sunrise or before sunset.

Golden hour usually occurs while the Sun is above the horizon, although some photographic definitions extend slightly into civil twilight.

The exact visual effect depends on clouds, humidity, pollution, terrain, and atmospheric particles.

Weather Can Change Perceived Light Levels

Calculated twilight times describe the Sun’s geometric position, but actual brightness can vary significantly.

Heavy clouds may make civil twilight feel much darker than expected. Snow cover can reflect light and make the landscape appear brighter. Smoke, haze, fog, and precipitation can also change visibility and sky color.

The Moon may provide substantial illumination after astronomical twilight, particularly near a full moon. Artificial lighting can make urban areas appear bright long after natural twilight has ended.

Twilight times should therefore be treated as a consistent astronomical reference, not as a guarantee of a particular visibility level.

How to Retrieve Twilight Data Using Visual Crossing Weather

The Visual Crossing Timeline Weather API provides sunrise, sunset, and all three standard twilight periods alongside historical weather observations and forecast data.

This makes it possible to retrieve astronomical information and weather conditions in the same request. For example, an application can combine civil dusk with cloud cover, visibility, precipitation, or moon information to determine how much usable outdoor light is likely to remain.

Twilight information is available in the daily records returned by the Timeline Weather API. It can be retrieved for:

Historical dates
Current conditions and recent dates
The 15-day weather forecast
Longer future periods using statistical forecast data
A single location or a series of location queries

The API supports locations entered as addresses, cities, postal codes, latitude-and-longitude coordinates, or supported location identifiers.

Visual Crossing Twilight Data Fields

The following daily elements describe sunrise, sunset, and twilight:

API element	Description
`sunrise`	Local time when the upper edge of the Sun appears above the horizon
`sunriseEpoch`	Sunrise expressed as UNIX seconds in UTC
`sunset`	Local time when the upper edge of the Sun disappears below the horizon
`sunsetEpoch`	Sunset expressed as UNIX seconds in UTC
`solarnoon`	Local time when the Sun reaches its highest point
`civildawn`	Beginning of morning civil twilight
`civildusk`	End of evening civil twilight
`nauticaldawn`	Beginning of morning nautical twilight
`nauticaldusk`	End of evening nautical twilight
`astronomicdawn`	Beginning of morning astronomical twilight
`astronomicdusk`	End of evening astronomical twilight

The dawn fields indicate when the corresponding morning twilight period begins. The dusk fields indicate when that evening twilight period ends.

For example:

Morning civil twilight runs from civildawn until sunrise.
Evening civil twilight runs from sunset until civildusk.
Full astronomical night generally runs from astronomicdusk until the following day’s astronomicdawn.

The twilight fields use local HH:mm:ss times for the requested location. Sunrise and sunset are also available as UTC-based epoch values for applications that need time-zone-independent processing.

Requesting Twilight Data from the Timeline Weather API

A basic Timeline Weather API request uses the following structure:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/LOCATION/START_DATE/END_DATE?key=YOUR_API_KEY

The location can be a city, address, postal code, or latitude-and-longitude pair. The dates can represent a historical period, forecast period, or a mixture of past and future dates.

For example, this request retrieves the daily forecast for Herndon, Virginia:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA?unitGroup=us&key=YOUR_API_KEY&include=days

Astronomical information is included in daily Timeline API data by default. However, applications that only need daylight and twilight values can use the elements parameter to reduce the response size.

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA?unitGroup=us&key=YOUR_API_KEY&include=days&elements=datetime,sunrise,sunset,solarnoon,civildawn,civildusk,nauticaldawn,nauticaldusk,astronomicdawn,astronomicdusk

The important parameters in this request are:

include=days requests daily records, where the twilight values are reported.
elements= limits the returned fields to the values needed by the application.
key= supplies the user’s Visual Crossing Weather API key.
unitGroup= controls weather measurement units, although it does not change the twilight times.

The response also identifies the location’s resolved time zone and UTC offset, helping applications interpret the local astronomical times correctly.

Example JSON Twilight Data

A daily record may contain values similar to the following:

{
  "datetime": "2026-07-22",
  "sunrise": "06:01:23",
  "sunriseEpoch": 1784714483,
  "sunset": "20:29:18",
  "sunsetEpoch": 1784766558,
  "solarnoon": "13:15:20",
  "civildawn": "05:31:58",
  "civildusk": "20:58:42",
  "nauticaldawn": "04:55:31",
  "nauticaldusk": "21:35:08",
  "astronomicdawn": "04:15:18",
  "astronomicdusk": "22:15:20"
}

In the JSON response, these values appear within each object in the days array:

const day = weatherData.days[0];

console.log("Sunrise:", day.sunrise);
console.log("Sunset:", day.sunset);
console.log("Civil dawn:", day.civildawn);
console.log("Civil dusk:", day.civildusk);
console.log("Nautical dawn:", day.nauticaldawn);
console.log("Nautical dusk:", day.nauticaldusk);
console.log("Astronomical dawn:", day.astronomicdawn);
console.log("Astronomical dusk:", day.astronomicdusk);

Retrieving Historical Twilight Data

The same endpoint can retrieve twilight information for a past date.

For example, this request returns sunrise, sunset, and twilight information for October 4, 2020:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA/2020-10-04?unitGroup=us&key=YOUR_API_KEY&include=days&elements=datetime,sunrise,sunset,civildawn,civildusk,nauticaldawn,nauticaldusk,astronomicdawn,astronomicdusk

A historical date range can be requested by adding both a start date and an end date:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA/2020-10-04/2020-10-10?unitGroup=us&key=YOUR_API_KEY&include=days&elements=datetime,sunrise,sunset,civildawn,civildusk,nauticaldawn,nauticaldusk,astronomicdawn,astronomicdusk

Because the Timeline API uses a single endpoint for historical and forecast information, applications do not need separate astronomy APIs for past and future dates.

Downloading Twilight Data as CSV

To retrieve tabular data for a spreadsheet, database, or analytical workflow, add:

contentType=csv

For example:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA/2026-07-01/2026-07-31?unitGroup=us&key=YOUR_API_KEY&include=days&elements=datetime,sunrise,sunset,civildawn,civildusk,nauticaldawn,nauticaldusk,astronomicdawn,astronomicdusk&contentType=csv

The resulting file contains one row per day and can be opened directly in applications such as Microsoft Excel or imported into a database.

A simplified result might look like this:

datetime,sunrise,sunset,civildawn,civildusk,nauticaldawn,nauticaldusk,astronomicdawn,astronomicdusk
2026-07-22,06:01:23,20:29:18,05:31:58,20:58:42,04:55:31,21:35:08,04:15:18,22:15:20

Building the Request Without Writing Code

The Visual Crossing Weather Query Builder can be used to select a location, date range, output format, and weather elements interactively.

After configuring the query, users can:

Preview the returned weather data
Download the results
Switch to the API view
Copy the generated Timeline Weather API request
Use the request as the starting point for an application or script

This is particularly useful when testing twilight fields or confirming the response format before adding the request to production code.

Combining Twilight and Weather Conditions

One advantage of retrieving twilight information through a weather API is that astronomical times can be combined with actual forecast or historical weather conditions.

A request could include:

datetime,sunrise,sunset,civildawn,civildusk,cloudcover,visibility,precipprob,conditions,moonphase

These fields can support questions such as:

Will skies be clear during astronomical twilight?
Will rain or fog reduce visibility before civil dusk?
How much usable light will remain at the end of an outdoor event?
Will a nearly full Moon affect astrophotography after astronomical dusk?
Should an outdoor work shift end at sunset or at civil dusk?
Will cloud cover make conditions appear darker earlier than the calculated twilight time?

For example:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA?unitGroup=us&key=YOUR_API_KEY&include=days&elements=datetime,sunrise,sunset,civildawn,civildusk,astronomicdawn,astronomicdusk,cloudcover,visibility,precipprob,conditions,moonphase

Calculated twilight times describe the Sun’s position, while weather fields describe the conditions that affect how bright or visible the environment will actually be.

Calculating Usable-Light Duration

Applications can calculate several useful daylight periods from the returned values:

Official daylight duration

sunset − sunrise

Civil-light window

civildusk − civildawn

Morning civil twilight duration

sunrise − civildawn

Evening civil twilight duration

civildusk − sunset

The civil-light window is often more useful than official day length for construction, recreation, agriculture, and other outdoor operations because it represents the broader period during which useful natural illumination may be available.

Developers should parse the local time values in the location’s reported time zone rather than assuming that the requested location uses the application server’s time zone.

High-Latitude and Polar Locations

Twilight events do not occur every day at every location.

At high latitudes, the Sun may remain above the horizon throughout the day, remain below it throughout the day, or fail to descend far enough for one or more twilight boundaries to occur.

For example:

The Sun may set without reaching astronomical dusk.
Civil twilight may continue throughout the night.
Sunrise or sunset may not occur on a particular local date.
Astronomical night may disappear entirely during part of the summer.

When an astronomical event does not occur, the corresponding API field may be empty. Applications should therefore allow twilight, sunrise, and sunset fields to contain null or missing values rather than assuming that every field will always contain a time.

How to Retrieve Twilight Data Using the Visual Crossing Weather API

The Visual Crossing Timeline Weather API can return civil, nautical, and astronomical twilight information alongside historical weather data, current conditions, forecasts, weather statistics, and other astronomical information.

Unlike sunrise, sunset, and moon phase, however, twilight fields are not included in the standard response by default. Applications must explicitly request at least one twilight element using the elements parameter.

This is an important distinction:

sunrise, sunset, and moonphase are normally included in daily Timeline API data.
Civil, nautical, and astronomical twilight fields are opt-in.
solarnoon must also be explicitly requested when it is needed.

A request that includes only:

include=days

will not normally return the twilight fields. They must be added explicitly.

Available Twilight Elements

The local-time twilight elements are:

API element	Description	Returned value
`civildawn`	Beginning of morning civil twilight, when the Sun reaches 6 degrees below the horizon	Local `HH:mm:ss`
`civildusk`	End of evening civil twilight, when the Sun reaches 6 degrees below the horizon	Local `HH:mm:ss`
`nauticaldawn`	Beginning of morning nautical twilight, when the Sun reaches 12 degrees below the horizon	Local `HH:mm:ss`
`nauticaldusk`	End of evening nautical twilight, when the Sun reaches 12 degrees below the horizon	Local `HH:mm:ss`
`astronomicdawn`	Beginning of morning astronomical twilight, when the Sun reaches 18 degrees below the horizon	Local `HH:mm:ss`
`astronomicdusk`	End of evening astronomical twilight, when the Sun reaches 18 degrees below the horizon	Local `HH:mm:ss`
`solarnoon`	Time when the Sun reaches its highest point in the sky for the local day	Local `HH:mm:ss`

The API field names are astronomicdawn and astronomicdusk. Although the period itself is normally called astronomical twilight, the API element names use astronomic without the final “al.”

Epoch Versions of Twilight Data

Each twilight field is also available as an epoch value:

Local-time element	Epoch element
`civildawn`	`civildawnEpoch`
`civildusk`	`civilduskEpoch`
`nauticaldawn`	`nauticaldawnEpoch`
`nauticaldusk`	`nauticalduskEpoch`
`astronomicdawn`	`astronomicdawnEpoch`
`astronomicdusk`	`astronomicduskEpoch`
`solarnoon`	`solarnoonEpoch`

The local-time fields are returned as times such as:

05:31:58

The epoch fields are returned as UNIX timestamps in seconds and provide a convenient UTC-based representation for calculations, comparisons, and time-zone conversion.

Sunrise and sunset follow the same pattern:

Local-time element	Epoch element
`sunrise`	`sunriseEpoch`
`sunset`	`sunsetEpoch`

Applications can therefore choose between human-readable local times and UTC-based epoch values, or request both.

Adding Twilight Fields to a Standard Weather Request

The simplest way to retrieve twilight data while preserving the normal Timeline Weather API response is to add the fields using the elements parameter.

For example:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/39.0035,-77.3674?unitGroup=us&include=days&elements=%2Bcivildawn,%2Bcivildusk,%2Bnauticaldawn,%2Bnauticaldusk,%2Bastronomicdawn,%2Bastronomicdusk,%2Bsolarnoon&key=YOUR_API_KEY

The decoded elements value is:

+civildawn,+civildusk,+nauticaldawn,+nauticaldusk,+astronomicdawn,+astronomicdusk,+solarnoon

The leading + tells the API to add those fields to the standard element set rather than replacing the standard fields.

Because a plus sign in a URL query string may otherwise be interpreted as a space, it should be encoded as:

%2B

This additive form is particularly useful when twilight data is being added to an existing weather request.

Requesting Local Times and Epoch Values

An application that needs both local twilight times and UTC-based epoch values can request them together:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/39.0035,-77.3674?unitGroup=us&include=days&elements=%2Bcivildawn,%2BcivildawnEpoch,%2Bcivildusk,%2BcivilduskEpoch,%2Bnauticaldawn,%2BnauticaldawnEpoch,%2Bnauticaldusk,%2BnauticalduskEpoch,%2Bastronomicdawn,%2BastronomicdawnEpoch,%2Bastronomicdusk,%2BastronomicduskEpoch,%2Bsolarnoon,%2BsolarnoonEpoch&key=YOUR_API_KEY

This approach is useful when the local times will be displayed to users but epoch timestamps will be used internally for calculations.

Requesting Only Twilight and Daylight Fields

When only daylight and twilight information is required, list the desired elements without the leading plus signs.

For example:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/39.0035,-77.3674?unitGroup=us&include=days&elements=datetime,sunrise,sunriseEpoch,sunset,sunsetEpoch,solarnoon,solarnoonEpoch,civildawn,civildawnEpoch,civildusk,civilduskEpoch,nauticaldawn,nauticaldawnEpoch,nauticaldusk,nauticalduskEpoch,astronomicdawn,astronomicdawnEpoch,astronomicdusk,astronomicduskEpoch&key=YOUR_API_KEY

Without the leading +, the elements parameter acts as a field selection. The response is limited to the requested elements rather than returning the normal weather element set.

This can substantially reduce response size for applications that only need astronomical data.

A Full Weather and Twilight Request

Twilight data can also be added to a larger weather request containing daily, hourly, current, forecast, observation, alert, statistics, and remote-sensing data.

For example:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/39.0035,-77.3674?unitGroup=us&include=days,hours,current,alerts,stats,obs,fcst,remote&iconSet=icons2&elements=%2Buvindex2,%2Baqius,%2Bcivildawn,%2Bcivildusk,%2Bnauticaldawn,%2Bnauticaldusk,%2Bastronomicdawn,%2Bastronomicdusk,%2Bsolarnoon,%2BmoonriseEpoch,%2BmoonsetEpoch&options=usev2forecast,era5stats&key=YOUR_API_KEY

This type of request is useful when twilight is one part of a broader weather application.

For example, an application could combine:

civildusk with cloud cover and visibility to estimate the end of usable outdoor light
astronomicdusk with cloud cover and Moon information to plan astronomical observations
nauticaldawn with visibility and wind data for marine operations
Sunrise and sunset with solar radiation or UV data
Twilight boundaries with current conditions, forecasts, and weather alerts

The twilight calculation and response fields are part of the shared Timeline API data model. Applications should nevertheless use the documented production /timeline/ endpoint when building production requests.

Where Twilight Values Appear

Twilight values describe the astronomical conditions for an entire local day. They are therefore returned as daily properties within each object in the JSON days array.

A response may contain a daily record similar to:

{
  "days": [
    {
      "datetime": "2026-07-22",
      "sunrise": "06:01:23",
      "sunriseEpoch": 1784714483,
      "sunset": "20:29:18",
      "sunsetEpoch": 1784766558,
      "civildawn": "05:31:58",
      "civildawnEpoch": 1784712718,
      "civildusk": "20:58:42",
      "civilduskEpoch": 1784768322,
      "nauticaldawn": "04:55:31",
      "nauticaldawnEpoch": 1784710531,
      "nauticaldusk": "21:35:08",
      "nauticalduskEpoch": 1784770508,
      "astronomicdawn": "04:15:18",
      "astronomicdawnEpoch": 1784708118,
      "astronomicdusk": "22:15:20",
      "astronomicduskEpoch": 1784772920,
      "solarnoon": "13:15:20",
      "solarnoonEpoch": 1784740520
    }
  ]
}

The precise order of fields in the JSON response is not significant. Applications should read properties by name rather than depending on their serialized order.

The top-level response also identifies the resolved location and time zone:

{
  "timezone": "America/New_York",
  "tzoffset": -4
}

The local-time twilight values should be interpreted using the returned location time zone, not the time zone of the application server or the person making the request.

The epoch versions avoid this ambiguity because they represent absolute points in time.

Retrieving Twilight Data as CSV

Twilight information can also be returned in CSV format by adding:

contentType=csv

For example:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/39.0035,-77.3674/2026-07-01/2026-07-31?unitGroup=us&include=days&elements=datetime,sunrise,sunset,solarnoon,civildawn,civildusk,nauticaldawn,nauticaldusk,astronomicdawn,astronomicdusk&contentType=csv&key=YOUR_API_KEY

This returns one daily row for each requested date and can be opened in Microsoft Excel, imported into a database, or processed by a script.

Epoch fields can also be included when the CSV will be used for time calculations:

elements=datetime,civildawn,civildawnEpoch,civildusk,civilduskEpoch,astronomicdawn,astronomicdawnEpoch,astronomicdusk,astronomicduskEpoch

Historical and Forecast Twilight Data

The same Timeline API endpoint can retrieve twilight data for past and future dates.

A historical date:

/timeline/39.0035,-77.3674/2020-10-04

A historical date range:

/timeline/39.0035,-77.3674/2020-10-04/2020-10-10

A dynamic date period:

/timeline/39.0035,-77.3674/last30days

A request without dates returns the normal forecast period:

/timeline/39.0035,-77.3674

In every case, the desired twilight elements must still be explicitly included in the elements parameter.

For example:

elements=%2Bcivildawn,%2Bcivildusk,%2Bnauticaldawn,%2Bnauticaldusk,%2Bastronomicdawn,%2Bastronomicdusk

The fact that a request includes daily data does not by itself enable the twilight fields.

Combining Twilight and Weather Conditions

One advantage of retrieving twilight through the Timeline Weather API is that the astronomical times can be returned alongside the actual weather conditions that affect outdoor brightness and visibility.

Useful companion fields include:

cloudcover
visibility
precip
precipprob
conditions
moonphase
moonriseEpoch
moonsetEpoch
solarradiation
solarenergy
uvindex

These combinations can answer practical questions such as:

Will skies be clear during astronomical twilight?
Will rain, fog, or low cloud reduce visibility before civil dusk?
How much usable natural light may remain at the end of an outdoor event?
Will moonlight affect astrophotography after astronomical dusk?
Should an outdoor work period end at sunset or civil dusk?
Will dense cloud cover make conditions appear dark before the calculated twilight boundary?

Twilight fields describe the geometric position of the Sun. Weather fields describe the atmospheric conditions that determine how bright the environment will actually appear.

Calculating Daylight and Twilight Durations

Epoch values provide the simplest method for calculating daylight and twilight durations.

Official daylight duration:

sunsetEpoch - sunriseEpoch

Morning civil twilight duration:

sunriseEpoch - civildawnEpoch

Evening civil twilight duration:

civilduskEpoch - sunsetEpoch

Total civil-light window:

civilduskEpoch - civildawnEpoch

Astronomical night can be calculated using the evening astronomical dusk and the following day’s astronomical dawn:

nextDay.astronomicdawnEpoch - astronomicduskEpoch

The result of each subtraction is in seconds.

For many outdoor activities, the civil-light window is more useful than the official sunrise-to-sunset duration because it represents the broader period during which natural outdoor illumination may be available.

Handling Missing Twilight Events

At high latitudes, a particular sunrise, sunset, or twilight boundary may not occur on every local date.

For example:

The Sun may remain above the horizon throughout the day.
The Sun may remain below the horizon throughout the day.
The Sun may set but never reach 18 degrees below the horizon.
Civil or nautical twilight may continue throughout the night.
Astronomical night may not occur during summer.

When an event does not occur, its corresponding local-time and epoch fields may be empty or null.

Applications should therefore:

Explicitly request the required twilight elements.
Check that each value exists before using it.
Avoid assuming that every location has every twilight event every day.
Use the epoch fields for duration calculations whenever possible.
Use the local-time fields for display in the requested location’s time zone.

Building a Twilight Request

A typical application workflow is:

Submit a Timeline Weather API request for a location and date range.
Include days in the include parameter.
Explicitly add the required twilight fields through elements.
Request local-time fields, epoch fields, or both.
Read the values from each object in the JSON days array or from the CSV rows.
Use the returned time zone when displaying local times.
Check for null values at high-latitude locations.
Combine twilight with cloud cover, visibility, precipitation, Moon, or solar data when actual outdoor light conditions matter.

By returning twilight and weather data through a single endpoint, the Visual Crossing Timeline Weather API supports applications involving outdoor operations, aviation, navigation, photography, astronomy, travel, recreation, energy use, and other light-sensitive activities.

Summary

Day does not turn into night immediately at sunset. Instead, the sky moves through three progressively darker stages of twilight.

Civil twilight provides enough natural light for many normal outdoor activities.
Nautical twilight leaves a visible horizon while brighter stars become prominent.
Astronomical twilight is the final stage before the sky becomes fully dark.
Astronomical night begins when the Sun is more than 18 degrees below the horizon.

Understanding these stages provides a more useful picture of natural light than sunrise and sunset times alone. Whether you are planning outdoor work, travel, photography, navigation, or astronomical observation, twilight data can help identify when usable light begins, when it fades, and when true darkness arrives.