In addition to providing historical weather observations and weather forecast data, the Weather API also provides a full set of astronomical information. This includes sunrise and sunset, the three twilight phases (civil, nautical and astronomical), solar noon, moonrise and moonset, the moon phase, the Moon’s azimuth and elevation in the sky, and the Earth–Moon distance.
Why is astronomical information useful?
Sunset, sunrise, twilight and moon information go hand-in-hand with weather data in many use cases. The information can help answer some basic questions:
- Is it daylight at a particular time? – critical for insurance and risk analysis where daylight or darkness can increase the likelihood or seriousness of an event.
- What is the length of the day? – important for agricultural situations where the amount of daylight corresponds to growing seasons.
- Event planning – understanding whether an event will be during daylight, twilight or evening to help with logistics and lighting.
- Recreation – many recreation activities demand either daylight or even darkness to be successful. If you are an astronomer, you need it dark and may want the Moon to be either prominent or hidden depending on what celestial bodies you are observing.
- Dark-skies prediction – for astronomy, hunting or fishing where a bright, full moon may hinder the activity. The Moon’s elevation tells you whether it is actually above the horizon at the time of interest, not just what phase it is in.
- Civil, nautical and astronomical twilight – for aviation, marine navigation, photography and observatory operations, where the level of residual sunlight in the sky matters as much as whether the Sun has technically set.
- Tides and supermoon detection – the Earth–Moon distance varies through the orbit and contributes to tidal range and the apparent size of the lunar disk.
Astronomical elements reference
| Element | Description | Units |
|---|---|---|
sunrise | Local sunrise time | HH:mm:ss (or ISO 8601 on legacy endpoints) |
sunriseEpoch | Sunrise as UNIX seconds (UTC) | seconds |
sunset | Local sunset time | HH:mm:ss (or ISO 8601 on legacy endpoints) |
sunsetEpoch | Sunset as UNIX seconds (UTC) | seconds |
solarnoon | Local time of maximum solar elevation | HH:mm:ss |
civildawn | Start of civil twilight (Sun 6° below horizon, before sunrise) | HH:mm:ss |
civildusk | End of civil twilight (Sun 6° below horizon, after sunset) | HH:mm:ss |
nauticaldawn | Start of nautical twilight (Sun 12° below horizon, before sunrise) | HH:mm:ss |
nauticaldusk | End of nautical twilight (Sun 12° below horizon, after sunset) | HH:mm:ss |
astronomicdawn | Start of astronomical twilight (Sun 18° below horizon, before sunrise) | HH:mm:ss |
astronomicdusk | End of astronomical twilight (Sun 18° below horizon, after sunset) | HH:mm:ss |
moonphase | Lunar phase, 0 = new moon, 0.5 = full moon | 0–1 |
moonriseEpoch | Moonrise as UNIX seconds (UTC); empty if no moonrise that day | seconds |
moonsetEpoch | Moonset as UNIX seconds (UTC); empty if no moonset that day | seconds |
moonazimuth | Compass bearing to the Moon, clockwise from true north | degrees |
moonelevation | Angular height of the Moon above the horizon (negative = below) | degrees |
moondistance | Earth–Moon centre-to-centre distance | km |
Moon phase number
The moon phase number represents the fractional portion through the current moon lunation cycle ranging from 0 (the new moon) to 0.5 (the full moon) and back to 1 (the next new moon). These numbers are similar to other Weather API providers so converting existing applications is easy.
Traditional, western moon cycles are therefore represented by the following values:
- 0 – new moon
- 0-0.25 – waxing crescent
- 0.25 – first quarter
- 0.25-0.5 – waxing gibbous
- 0.5 – full moon
- 0.5-0.75 – waning gibbous
- 0.75 – last quarter
- 0.75 -1 – waning crescent
Moon phases are reported at midday local time. On days where a quarterly phase occurs (new moon, first quarter, full moon and last quarter) the values are rounded to the quarterly phase value (0, 0.25, 0.5, 0.75). Therefore you can identify the quarterly days by identifying days with these values.
Sun and Moon rise and set times
The Timeline Weather API includes the ability to retrieve the Sun and Moon rise and set times. Notice that in some cases these may be missing because they do not apply. For example, the Moon may not rise and set every day (particularly in higher latitudes). In addition, while the Sun always sets after the Sun rises on the same day, the Moon may set in the morning and rise in the afternoon as the Moon’s orbit is not based on the Earth day.
sunrise and sunset are returned as local HH:mm:ss times. sunriseEpoch and sunsetEpoch give the same instants as UNIX seconds in UTC, which is convenient for sorting, math, and time-zone-independent processing. moonriseEpoch and moonsetEpoch are the equivalent UNIX-second values for the Moon; on days with no moonrise or no moonset within the local calendar day the corresponding field is empty.
Solar noon
solarnoon is the local time at which the Sun reaches its highest point in the sky for the day. This is the midpoint between sunrise and sunset and is the moment of maximum solar elevation. Solar noon usually differs from clock noon (12:00) because of the location’s longitude within its time zone and the equation of time.
Twilight: civil, nautical and astronomical
Twilight is the period before sunrise and after sunset when the Sun is below the horizon but still illuminates the sky. Visual Crossing reports the three standard twilight boundaries:
- Civil twilight (
civildawn,civildusk) – the Sun is between 0° and 6° below the horizon. There is enough natural light for most outdoor activities without artificial lighting; the brightest stars and planets become visible. - Nautical twilight (
nauticaldawn,nauticaldusk) – the Sun is between 6° and 12° below the horizon. The horizon at sea is still distinguishable and major navigational stars are visible, which is the historical basis for celestial navigation. - Astronomical twilight (
astronomicdawn,astronomicdusk) – the Sun is between 12° and 18° below the horizon. The sky is dark enough for most astronomical observations; outside of this window the sky is no longer affected by scattered sunlight.
*dawn values mark the start of each twilight phase before sunrise; *dusk values mark the end of each twilight phase after sunset. As with sunrise and sunset, these may be empty at very high latitudes where the Sun does not descend far enough below the horizon.
Moon position and distance
In addition to the moon phase and rise/set times, Visual Crossing reports the instantaneous position of the Moon in the sky and its distance from Earth:
moonazimuth– the compass direction to the Moon, measured in degrees clockwise from true north (0° = north, 90° = east, 180° = south, 270° = west).moonelevation– the angular height of the Moon above the local horizon, in degrees. Values range from -90° (directly below the observer) to +90° (directly overhead). Negative values mean the Moon is below the horizon and not visible at that time.moondistance– the distance from the centre of the Earth to the centre of the Moon, in kilometres. The Moon’s orbit is elliptical, so this typically varies between about 356,500 km at perigee (closest approach) and 406,700 km at apogee (farthest point). Useful for tide modelling, supermoon detection, and any application that depends on the apparent size of the lunar disk.
For daily requests, moonazimuth and moonelevation are reported at local solar noon; for hourly requests they are reported at the top of each hour.
Example payload
A daily record from the Timeline API including the full astronomical element set looks like this:
"sunrise": "05:36:22",
"sunriseEpoch": 1777437382,
"sunset": "20:20:36",
"sunsetEpoch": 1777490436,
"moonphase": 0.42,
"moonriseEpoch": 1777482972,
"moonsetEpoch": 1777433420,
"civildawn": "04:58:35",
"civildusk": "20:58:37",
"nauticaldawn": "04:10:02",
"nauticaldusk": "21:47:36",
"astronomicdawn": "03:10:57",
"astronomicdusk": "22:47:40",
"solarnoon": "12:57:56",
"moonazimuth": 15.7,
"moonelevation": -45.7,
"moondistance": 395952.7
How to request astronomical information in the Weather API
The Timeline Weather API includes the astronomy information for historical observations and daily forecasts by default. When you request historical information or weather forecast data, the sunset, sunrise, twilight, solar noon, moon phase and lunar position fields will be included. The Timeline API allows you to request historical and forecast data seamlessly in a single request.
The following timeline request looks up the moon phase, sunrise and sunset for the next 15 days in a JSON format. The astronomical properties will be included along with standard weather forecast properties:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA?unitGroup=us&key=YOUR_API_KEY&include=days
The optional elements parameter is used to filter all other properties from the request.
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA?unitGroup=us&key=YOUR_API_KEY&include=days&elements=datetime,moonphase,sunrise,sunset,moonrise,moonset
The full astronomical element set including twilight, solar noon and lunar position:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA?unitGroup=us&key=YOUR_API_KEY&include=days&elements=datetime,sunrise,sunriseEpoch,sunset,sunsetEpoch,solarnoon,civildawn,civildusk,nauticaldawn,nauticaldusk,astronomicdawn,astronomicdusk,moonphase,moonriseEpoch,moonsetEpoch,moonazimuth,moonelevation,moondistance
If you would prefer a CSV output, you can add a ‘contentType’ parameter:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA?unitGroup=us&key=YOUR_API_KEY&include=days&elements=datetime,moonphase,sunrise,sunset&contentType=csv
You can also request the same information for a single date, a date range or a dynamic date range:
For the 4th October 2020:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA/2020-10-04?unitGroup=us&key= YOUR_API_KEY &include=days&elements=datetime,moonphase,sunrise,sunset&contentType=csv
For the 4th October 2020 to the 10th October 2020:
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,moonphase,sunrise,sunset&contentType=csv
For the last7 days (which will adjust dynamically):
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon,VA/last7days?unitGroup=us&key= YOUR_API_KEY &include=days&elements=datetime,moonphase,sunrise,sunset&contentType=csv
See the full Timeline Weather API Documentation for additional information on the available properties and parameters.
Where to find more information
If you need more information on the weather API and the results, check out the weather API documentation, weather data documentation and JSON format documentation.
Questions or need help?
If you have a question or need help, please post on our actively monitored forum for the fastest replies. You can also contact our Support Team.