Timeline Weather API

The Timeline Weather API is the simplest and most powerful way to retrieve weather data. You can request data over any time window including windows that span the past, present, and future. The API will take care of the complexity of combining historical observations, current 15-day forecasts, and statistical weather forecasts to create a single, consolidated dataset via a single API call.

The Timeline API offers complete, global weather data coverage both geographically and chronologically. It always picks the best available data sources to answer any weather API query. These sources include:

  • Current weather conditions
  • Daily historical, forecast and statistical forecast data (depending on dates requested)
  • Hourly historical observations and 15-day forecast
  • Weather alerts
  • Astronomical observations including sunrise, sunset and moon phase.

Result data is provided in a common JSON format allowing you to ignore to complex underlying data sources and focus entirely on your weather data use case.

Migrating from Dark Sky

The Timeline Weather API provides a simple migration path for existing Dark Sky API users. If you are replacing your existing Dark Sky API implementation in an app or website, read our step-by-step conversion guide.

Timeline Weather API Query Builder

The Weather Data Services page includes a full, interactive query builder so you can create queries and see the live results directly in your browser.

API Request Types

All requests to the Timeline Weather API use the following the form:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/[location]/[date1]/[date2]?key=YOUR_API_KEY 

location (required) – is the address, partial address or latitude,longitude location for which to retrieve weather data. You can also use US ZIP Codes.

date1 (optional) – is the start date for which to retrieve weather data. If a date2 value is also given, then it represents the first date for which to retrieve weather data. If no date2 is specified then weather data for a single day is retrieved, and that date is specified in date1. All dates and times are in local time of the location specified. Dates should be in the format yyyy-MM-dd. For example 2020-10-19 for October 19th, 2020 or 2017-02-03 for February 3rd, 2017.

Instead of an exact date, you can specify a dynamic date period. See below for more details.

date2 (optional) – is the end date for which to retrieve weather data. This value may only be used when a date1 value is given. When both date1 and date2 values are given, the query is inclusive of date2 and the weather data request period will end on midnight of the date2 value. All dates and times are in local time of the specified location and should be in the format yyyy-MM-dd.

When no date1 or date2 is specified, the request will retrieve the forecast at the requested location for the next 15 days.

Forecast Request Example

The following will retrieve the weather forecast for London, United Kingdom for the next 15 days, starting at midnight at the start of the current day (local time of the requested location).

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK?key=YOUR_API_KEY 

Date Range Request Example

The following will retrieve the weather data for London, UK from October 1st, 2020 to December 31st, 2020 (inclusive).

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK/2020-10-01/2020-12-31?key=YOUR_API_KEY 

Assuming the current date is November 1st, 2020, the result will include historical observations from October 1st to 31st, then 15 days of weather forecast and finally the remaining days will include the statistical forecast based on processing years of historical observations.

Dynamic period Request Example

Rather the specify and date range, you can also specify and dynamic period. A request based on a dynamic period will automatically adjust based on the period. In this example, we will use the dynamic period value “last30days” to retrieve data for the most recent 30 days.

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK/last30days?key=YOUR_API_KEY 

Other dynamic period values include “today”, “yesterday”, and “lastyear”. For a complete list of options and additional example, please see the dynamic period article.

Additional request parameters

The following are specified as HTTP query parameters (they may also be passed in a POST query).

key (required) – your API key. Sign up for a free account using our Weather Data Services page.

unitGroup (optional) – The system of units used for the output data.
Supported values are us, uk, metric, base. See Unit groups and measurement units for more information. Defaults to US system of units.

include (optional) – Specifies the sections you would like to include in the result dark. This allows you to reduce query cost and latency. Specify this as a comma separated list. For example: &include=obs,fcst to include the historical observations and forecast data. The options are:

  • obs – historical observations
  • fcst – Forecast
  • stats – Statistical Forecast
  • hours – Hourly data
  • alerts – Weather alerts
  • current – current conditions

Typical response format

All Timeline Weather API requests return response JSON in the same format. Here is an example for Reston, VA on 11/12/2020:

{
     "latitude" : 38.9697,
     "longitude" : -77.385,
     "resolvedAddress" : "Reston, VA, United States",
     "address" : " Reston,VA",
     "timezone" : "America/New_York",
     "tzoffset" : -5, 
     "days" : [{ //array of days of weather data objects
         "datetime":"2020-11-12",
         "datetimeEpoch":1605157200,
         "temp" : 59.6,
         "feelslike" : 59.6,
         ...
         "stations" : {
         },
         "source" : "obs",
         "hours" : [{  //array of hours of weather data objects  
             "datetime" : "01:00:00",
             ...
         },...]
     },...],
     "alerts" : [{
             "event" : "Flash Flood Watch",
             "description" : "...",
             ...
         }
     ],
     "currentConditions" : {
         "datetime" : "2020-11-11T22:48:35",
         "datetimeEpoch" : 160515291500,
         "temp" : 67.9,
         ...
     }
}

The response starts with a set of properties describing the location and request including the specific location requested, the resolved address, the latitude and longitude, a text based time zone and a time zone offset in hours. Note that the time zone offset can change within a dataset (based on daylight savings). If this occurs, the a tzoffset property will be found in the day, hour or current conditions weather data object.

The days array is an array of weather data objects for each day requested.

Within each day may be an hours array for the hourly information. Statistical forecast days will not include an hourly array.

If the request includes the current date, the current conditions and any weather alerts available for the location will be included.

Response weather data elements

The following are the list of properties in a day or hourly data object:

cloudcover – how much of the sky is covered in cloud ranging from 0-100%

conditions – textual description of the weather conditions

datetime – ISO formatted date, time or datetime value indicating the date and time of the weather data in the locale time zone of the requested location

datetimeEpoch – number of seconds since 1st January 1970 in UTC time

tzoffset – the time zone offset in hours. This will only occur in the data object if it is different from the global timezone offset.

dew – dew point temperature

feelslike – what the temperature feels like accounting for heat index or windchill

hours (days only) – array of hourly weather data objects

humidity – relative humidity in %

icon – a fixed, machine readable summary that can be used to display an icon

moonphase –  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)

normal – array of normal weather data values – Each weather data normal is an array of three values representing, in order, the minimum value over the statistical period, the mean value, and the maximum value over the statistical period.

offsetseconds (hourly only) – time zone offset for this weather data object in seconds – This value may change for a location based on daylight saving time observation.

precip – the amount of precipitation that fell or is predicted to fall in the period

precipcover (days only) – the proportion of hours where there was non-zero precipitation

precipprob (forecast only) – the likelihood of measurable precipitation ranging from 0% to 100%

pressure – the sea level atmospheric or barometric pressure in millibars

snow – the amount of snow that fell or is predicted to fall

snowdepth – the depth of snow on the ground

source –  the type of weather data used for this weather object. – Values include historical observation (“obs”), forecast (“fcst”) or statistical forecast (“stats”). The current data is indicated by “today”. Today is typically a combination of historical observations and forecast data.

stations (historical only) – the weather stations used when collecting an historical observation record

sunrise (day only) – The formatted time of the sunrise (For example “2020-10-28T07:33:15-04:00”)

sunriseEpoch – sunrise time specified as number of seconds since 1st January 1970 in UTC time

sunset – The formatted time of the sunset (For example “2020-10-28T18:12:55-04:00”)

sunsetEpoch – sunset time specified as number of seconds since 1st January 1970 in UTC time

temp – temperature at the location

tempmax (day only) – maximum temperature at the location.

tempmin (day only) – minimum temperature at the location.

visibility – distance at which distant objects are visible

winddir – direction from which the wind is blowing

windgust – instantaneous wind speed at a location – May be empty if it is not significantly higher than the wind speed.

windspeed – average wind speed over a minute

solarradiation – (W/m2) the solar radiation power at the instantaneous moment of the observation (or forecast prediction). See the full solar radiation data documentation.

solarenergy – (MJ or kWh) indicates the total energy from the sun that builds up over an hour or day. See the full solar radiation data documentation.

Leave a Reply

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