How to include sunrise, sunset and moon phase data into your API requests

In addition to providing historical weather observations and weather forecast data, the Weather API also provides astronomical information. This astronomical information includes sunset, sunrise and moon phase data.

Why is astronomical information useful?

Sunset, sunrise and moon information goes hand-in-hand with weather data in many use cases. The information can help answer some basic questions:

  1. 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.
  2. The length of the day – important for agricultural situations where the amount of daylight corresponds to growing seasons.
  3. Event planning – understanding whether an event will be during the daylight or evening to help planning.
  4. 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.

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 such as Dark Sky 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

How to request astronomical information in the Weather API

Timeline 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 and moon phase will be included. The Timeline API allows you to request historical and forecast data seamlessly in a single request.

Forecast and history endpoints

The Weather API can optionally include sunset, sunrise and moon phase in current conditions, weather forecast and historical weather data requests. To include the data in your results, simply add ‘includeAstronomy=true’ as a parameter in your request. As an example, the following will request the forecast and current conditions including the astronomy: 

If you want to try out the above URL, don’t forget to replace ‘YOUR_API_KEY’ with your API Key. If you don’t have one, you can sign up for a free account.

The results are returned in either CSV or JSON format. In this case we requested the JSON output format and so we will see the astronomical results in the current conditions and each of the forecast periods.

Here is the information for the current conditions:

"currentConditions" : {
    "sunrise" : "2020-07-31T06:09:52-04:00", 
    "sunset" : "2020-07-31T20:21:35-04:00", 
    "moonphase" : 0.44, 
    "wdir" : 113.0,
    "temp" : 72.9,
    "visibility" : null,
    "wspd" : 0.0,
    "icon" : "rain",
    "stations" : "",
    "heatindex" : null,
    "cloudcover" : null,
    "datetime" : "2020-07-31T11:00:19-04:00",
    "precip" : 0.9,
    "snowdepth" : null,
    "sealevelpressure" : null,
    "dew" : 71.5,
    "humidity" : 95.3,
    "wgust" : 2.0,
    "windchill" : null

The astronomical information at the top shows the sunrise, sunset and moonphase. The sunrise and sunset times are full ISO 8601 date times in the local time of the location requested.

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 us via our support site or drop us an email at

If you think you see wrong data, please read through our article on how to tell us so we can investigate and fix problems ASAP!