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

By /

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.
  5. Dark skies prediction – for astronomy, hunting or fishing where a bright, full moon may hinder the activity.

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

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 orbit is not based on the earth day.

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.

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

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.

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:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/forecast?aggregateHours=24&includeAstronomy=true&combinationMethod=aggregate&contentType=json&unitGroup=us&locationMode=single&key=YOUR_API_KEY&locations=Washington%2C%20DC%2C%20US

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 support@visualcrossing.com.

Scroll to Top