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.

How to request astronomical information in the Weather API

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.

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

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.

If you have questions, please ask below in the comments or contact support. Also if you have feature requests, let us know how we can help you!

Leave a Reply

Your email address will not be published. Required fields are marked *