Weather API Documentation

Introduction

The Visual Crossing Weather API provide a simple way to import weather and climate information into applications and back end systems. In addition, the web services allow developers to easily integrate weather data into web sites and other development projects.

This document explains the usage of the available web services including the input parameters and output datasets. Please follow our Twitter account for the latest in product updates
.

Weather API Samples & Demos

Prerequisites

To get started with the Weather API, it is necessary to sign up for a free trial account. You can sign up for free at weather data services page. In addition to providing sign up, this page also allows you to use the weather services to retrieve limited weather data. For the full range of weather data, and to use the web services in applications, please sign up. All the following examples require the use of an API key that you will obtain when signing up for the trial.

Usage and important notes

All the examples in this document provide unencoded values for clarity. It is recommended that all URL parameter be correctly encoded to ensure correct transmission. Some features or data volumes may not be available depending on the license level subscribed.

Weather API

There are three web service end points available to retrieve three types of weather data:

  • /forecast - provides access to weather forecast information
  • /history - provides access to hourly and daily historical weather records
  • /historysummary - provides access to historical weather reports and processed information

Weather forecast data - /forecast

Provides access to weather forecast information. The forecast is available for up to seven days at the hourly, 12 hour and daily summary level.

Sample request

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/forecast?&location=Herndon,VA,20170&aggregateHours=24&unitGroup=us&shortColumnNames=false&key=YOURAPIKEY

Parameters

location - The address or latitude or longitude of the location. Addresses can be specified as full addresses. The system will also attempt to match partial addresses such as city, state, zip code, postal code and other common formats. When specify a point based on longitude, latitude, the format must be specifed as latitude,longitude where both latitude and longitude are in decimal degrees. latitude should run from -90 to 90 and longitude from -180 to 180 (with 0 being at the prime meridian through London, UK).

aggregateHours -The interval between weather forecast data in the output. 1 represents an hourly forecast, 24 represents a daily forecast. As the source data is calculated at the hourly level, records calculated at 12 or 24 hours are aggregated to indicate the predominant weather condition during that time period. For example the maximum temperature, total precipitation, maximum windspeed etc.
Supported values 1,12 or 24.

unitGroup - The system of units used for the output data.
Supported values are us,uk,metric.

shortColumnNames - When false, the returned dataset includes descriptive column names. When true, returns shorter, abbreviated column names with only alphanumeric characters. The short names are useful for programmatic use of the data.

key - API key for your account.

Output format

The output data is a comma separated table format. Each row represents a forecast time frame (based upcon the aggregateHours parameter). The columns include information on the locations requested and the available weather forecast data.

Historical weather record - /history

The weather history data is suitable for retrieving hourly or daily historical weather records.

Sample request

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/history?&aggregateHours=24&startDateTime=2019-06-13T00:00:00&endDateTime=2019-06-20T00:00:00&unitGroup=uk&dayStartTime=0:0:00&dayEndTime=0:0:00&location=Sterling,VA,US&key=YOURAPIKEY

Parameters

location - The address or latitude or longitude of the location. See additional information in forecast.

aggregateHours -The interval between weather history data in the output. 1 represent hourly records, 24 represents a daily forecast. As the source data is recorded at the hourly level, 24 hour records are aggregated to indicate the predominant weather conditions during that time period.
Supported values 1 or 24.

unitGroup - The system of units used for the output data.
Supported values are us,uk,metric.

startDateTime - The date time for the start of the data request using the time zone of the location. In the ISO format: yyyy-MM-ddTHH:mm:ss. Hours should be specified in 24 hour clock format.

endDateTime - The date time for the start of the data request using the time zone of the location. In the ISO format: yyyy-MM-ddTHH:mm:ss. Hours should be specified in 24 hour clock format.

dayStartTime - When present and not set to the same as the dayEndTime, filters the output to records that between the specified day times. This is useful for setting filters for business hours. Format h:m:ss (eg 9:00:00 woudl be 9am).

dayEndTime - when present and not set to the same as the dayEndTime, filters the output to records that between the specified day times.

collectStationContribution (optional) Whether to include a column describing the weather stations that were used for a particular output record. This can vary at the individual record level if weather stations do not transmit a full record and other stations are used as back ups.

maxDistance(optional) The maximum distance in meters used to search for local weather stations (default 50000m). This setting is combined with the maxStations parameter to find local weather stations.

maxStations(optional) maximum number of weather stations used to calculate a weather record (default 3). Closer weather stations are weighted signficantly more heavily than farther stations.

shortColumnNames - When false, the returned dataset includes descriptive column names. When true, returns shorter, abbreviated column names with only alphanumeric characters. The short names are useful for programmatic use of the data.

key - API key for your account.

Output format

The output data is a comma separated table format. Each row represents a historical record at the hour or daily level (based upcon the aggregateHours parameter). The columns include information on the locations requested and the available weather history records.

Historical weather summaries - /historysummary

The weather summary reports provide aggregated weather data suitable for easy and quick summaries. For example, typical weather by year, month, week. How has the weather changed over time and other,

Sample request

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/history?&aggregateHours=24&startDateTime=2019-06-13T00:00:00&endDateTime=2019-06-20T00:00:00&unitGroup=uk&dayStartTime=0:0:00&dayEndTime=0:0:00&location=Sterling,VA,US&key=YOURAPIKEY

Parameters

location - The address or latitude or longitude of the location. See additional information in forecast.

chronoUnit - The unit of time used to create the summary report
Supported values are years, months, weeks, days

breakBy - How to aggregate the data across years and time periods. Breaking by 'years' indicates that individual years are returned in the output, breaking by 'self' indicates the same time period for all years is summarized. Breaking by 'none' collapses all records to a single summary row.
Supported values are years,self,none

unitGroup - The system of units used for the output data.
Supported values are us,uk,metric..

dailySummaries - Whether or not to include data for the day level means within the dataset.

shortColumnNames - When false, the returned dataset includes descriptive column names. When true, returns shorter, abbreviated column names with only alphanumeric characters. The short names are useful for programmatic use of the data.

maxDistance(optional) The maximum distance in meters used to search for local weather stations (default 50000m). This setting is combined with the maxStations parameter to find local weather stations.

maxStations(optional) maximum number of weather stations used to calculate a weather record (default 3). Closer weather stations are weighted signficantly more heavily than farther stations.

key - API key for your account.

Output format

The output data is a comma separated table format. Each row represents a historical summary record.

Questions or comments?

Please refer to our support site for additional articles, forums and to submit a support ticket.