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 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 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 three web service end points available to retrieve three types of weather data:

  • /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’

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

period – Named data time range used instead of the startDateTime and endDateTime parameters. Available period values are today, yesterday, yeartodate and monthtodate. 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 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 -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’

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

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 comments?

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

15 Replies to “Weather API Documentation”

  1. Hi,

    I am trying to understand which units relate to which setting

    UK – is that Celsius/mph/mm

    Metric – Celsius/kph/mm

    Can you send me a link or tell me which unit US metric UK relates to which measurements?

    Thank you 🙂

    Tricia.

  2. Hi, is the time I pass in the assumed to be UTC, or local? What about the time being returned? I’m retrieving historical values for localities in CET and it isn’t easy to spot the difference…

    1. Thank you for your question. The ‘Conditions’ field is currently available in English. We are currently working on expanding the number of languages supported across the Weather API. What languages are you interested in so we can add them to our technology plan?

      Regards
      Visual Crossing Support

  3. Hi,
    I am considering using your Historical weather record api but I couldn’t find any information about the oldest startDateTime possible.
    I would need data atleast for the last 10 years, would it be possible for every location?

    Thanks for your time

    1. Thank you for the question.

      The standard Visual Crossing Weather database extends back to 1970. However, the onset of the most accurate data and the most dense station availability begins in the late 1980s and early 1990s. From the 1990s through to the present day, you will be able to find high-quality and accurate global data.

      Much of the modern station network was built starting in the 1960s. So data in the 1970s and 1980s will be less dense in regard to station availability. Also, station maintenance was a problem during this period and some stations go offline for periods while others have periods of reporting erratic results for certain metrics. One common metric victim is precipitation. Visual Crossing’s ingesting and harmonizing process does its best to resolve problems during this period, but data from this era should always be examined a little more closely to ensure that the station(s) being used are close enough to the expected location, and that the most local station(s) do not go offline in the middle of a data set (forcing our system to pick another, less close station).

      For more information and details, please see our FAQ here: Frequently Asked Questions (FAQ) for Visual Crossing Weather Data

    1. Thank you for your question. We provide weather observations by daily, hourly and sub-hourly level (for example every 15 minutes).

      To switch between daily and hourly interval, use the ‘aggregateHours’ parameter of the API. Set it to 24 for daily and 1 for hourly data.

      Regards
      Visual Crossing Support

        1. I apologize for the confusion. Yes you can see hourly level historical summaries by setting the chronoUnit parameter to ‘hours’. For example, the following request will return the historical summary by hour of day:

          https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/historysummary?&minYear=2009&maxYear=2019&chronoUnit=hours&breakBy=self&contentType=csv&unitGroup=metric&key=YOUR_API_KEY&locations=London%2CUK

          Regards
          Visual Crossing Support

  4. Trying to parse json data (locations) that is sent back. The problem I am running into is the first entry is the Lat. and Lon. address and obj->[lat,lon] value is not working, using PHP….

    example:
    [locations] => stdClass Object
    (
    [10.73362482,-81.90401691] => stdClass Object
    (
    [stationContributions] =>
    [values] => Array
    (
    [0] => stdClass Object
    (
    [wdir] => 323
    [sunrise] => 2018-01-29T06:48:02-06:00
    [datetimeStr] => 2018-01-29T17:13:53-06:00
    [icon] => partly-cloudy-day
    [cloudcover] => 48.3
    [mint] => 46.7
    [mint] => ………..

    1. Thank you for your message.

      You should be able to retrieve the location latitude and longitude from the location object:
      Latitude, longitude: latitude; ?>, longitude; ?>

      If this doesn’t work, can you drop support an email at support@visualcrossing.com including a simple PHP script that shows the problem?

      Thank you
      Visual Crossing Support

Leave a Reply

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