Weather API Documentation

The Visual Crossing Weather API provides a simple way to import weather data 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.

WEATHER API SAMPLES & DEMOS

Prerequisites

To get started with the Weather API, it is necessary to sign up for a free account. You can sign up for free at  our weather data services page. In addition to providing sign up, this page also allows you to use the weather services to retrieve weather data and build the weather API queries described below. All the following examples require the use of an API key that you will obtain when signing up for the account.

Usage and important notes

All the examples in this document provide unencoded parameter 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.

Output data documentation

All the weather data APIs return consistent columns for weather forecast, historical weather and historical climate summary reports. To see the description of the data variables, see the Weather Data Documentation. For more information on the JSON output structure, see our JSON Result structure document.

contentType – JSON or CSV

The weather APIs return data in either tabular CSV format or JSON format. Most APIs allow the API user to choose between the output data format using the contentType parameter. To choose CSV data, include contentType=csv. To select JSON data, use contentType=json.

Weather API Endpoints

There are four web service endpoints available:

• /timeline – provides continuous weather data from historical observations, weather forecast and future statistical forecast based on previous conditions.
• /forecast – provides access to up to 15-days of 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 15 days at the hourly, 12 hour and daily summary level. Forecast requests for a single location also include the current conditions for that location when the output format is JSON.

Sample request

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

Parameters

locations – One or more address, partial address or latitude, longitude values for the required locations . 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 specified 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).

Data for multiple locations can be requested in a single request by concatenating multiple locations using the pipe (|) character.

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.

forecastDays – Integer indicating the maximum number of days of forecast to retrieve. For example, forecastDays=5 will return a 5 day forecast.

alertLevel – Retrieve weather alerts as part of a weather forecast. See Weather Alerts for more information

includeAstronomy – Retrieve astronomical data such as moonphase, sunrise and sunset times. Set to true to enable. See Astronomy Information for more information.

unitGroup – 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.

outputDateTimeFormat – specifies the date and time format used when returning the output.

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.

contentType – Selected between CSV or json output format. Supported values: ‘csv’ or ‘json’

locationMode– Requests the structure that will be used for the output locations in the JSON output format. Supported values: single,array, or lookup. See the JSON documentation for more information on how this parameters affects the output JSON structure

iconSet – returns fixed set of of the icons names based on the weather conditions. Currently supported value is ‘ icons1’

lang – Sets the language of the translatable parts of the output such as the conditions field. Available languages are en, de, fr and es. In addition passing in ‘id’ will result in the raw descriptor IDs.

key – API key for your account.

Output format

The output data is a comma separated table format or a JSON data structure. Each row represents a forecast time frame (based upon the aggregateHours parameter). The columns include information on the locations requested and the available weather forecast data. The JSON values include a JSON object per time period (for example hour or day). This JSON object has a parameter for each of the available weather element.

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&contentType=csv&dayStartTime=0:0:00&dayEndTime=0:0:00&location=Sterling,VA,US&key=YOURAPIKEY

Parameters

locations – One or more addresses or latitude, longitude values for the locations. 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. See also ‘aggregateMinutes’.
Supported values 1 or 24.

aggregateMinutes -The interval between weather history data in the output in minutes. This requires a plan that includes access to sub-hourly data. This parameter us used instead of ‘aggregateHours’. See Requesting sub-hourly weather data using the Weather API.

combinationMethod – Describes how multiple individual weather station observations should be combined. See Requesting sub-hourly weather data using the Weather API.

unitGroup – 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.

outputDateTimeFormat – specifies the date and time format used when returning the output.

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 end 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.

period – Named data time range used instead of the startDateTime and endDateTime parameters. Available period values are “today”,”yesterday”,tomorrow”,”yeartodate”,”last30days”,”lastyear”,”last24hours”,”next30days”,”next7days” and “nextyear”. The Timeline Weather API supports additional time periods. See Using Time Periods for more information.

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 would be 9am). When specified, the result can have no more than 30 days.

dayEndTime – when present and not set to the same as the dayEndTime, filters the output to records that between the specified day times. When specified, the result can have no more than 30 days.

timezone – specifies the timezone of the input and result dates and times. When not specified, all date times are considered local times. if you would like to specify that all dates are entered as UTC dates and times, use timezone=Z parameter.

collectStationContribution -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.

includeAstronomy – Retrieve astronomical data such as moon phase, sunrise and sunset times. Set to true to enable. See Astronomy Information for more information.

extendedStats – Retrieve additional statistical values in the weather request including mean, maximum and minimum of the wind speed, wind chill and heat index. Set to true to enable.

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 significantly 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 and database data import.

contentType – Selected between CSV or json output format. Supported values are ‘csv’ or ‘json’

locationMode– Requests the structure that will be used for the output locations in the JSON output format. Supported values: single,array, or lookup. See the JSON documentation for more information on how this parameters affects the output JSON structure.

key – API key for your account.

iconSet – returns fixed set of of the icons names based on the weather conditions. Currently supported value is ‘ icons1’

lang – Sets the language of the translatable parts of the output such as the conditions field. Available languages are en, de, fr and es. In addition passing in ‘id’ will result in the raw descriptor IDs.

Output format

The output data is a comma separated table (CSV) format or a JSON data structure. Each row represents a historical record at the hour or daily level (based upon 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/historysummary?aggregateHours=24&minYear=1989&maxYear=2019&chronoUnit=months&breakBy=self&dailySummaries=false&contentType=csv&unitGroup=us&locationMode=single&key=YOUR_API_KEY&locations=39.316219%2C%20-120.326001

Parameters

locations – One or more addresses or latitude, longitude values for the locations. 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

minYear– The initial year in the range of years to be summarized by this query
The weather database begins on 1/1/1970, so 1970 is the earliest allowable year.

maxYear– The final year in the range of years to be summarized by this query
You can specify any year between the minYear and the current calendar year inclusive.

unitGroup – 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.

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.

contentType – Selected between CSV or json output format. Supported values are ‘csv’ or ‘json’

locationMode– Requests the structure that will be used for the output locations in the JSON output format. Supported values: single,array, or lookup. See the JSON documentation for more information on how this parameters affects the output JSON structure.

key – API key for your account.

Output format

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

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.