Weather Data Documentation

The Visual Crossing Weather Data platform provides the ability to easily access weather data sets including weather forecast data, weather history data and historical weather summary data. The data is available for download through the Weather Data Download page and is also available through the Weather Data API.

This document explains the weather data variables that are available for the weather forecast and historical weather record datasets.

General weather data structure

We aim to keep the data set structure as consistent as possible between the three main categories of data – weather forecast, historical weather observations and historical weather summaries. This allows you to easily switch between using data for weather forecast and historical records within the same data and can be useful in many applications. All the data sets include the following characteristics:

Data Set Structure

All data sets are a simple table structure which is available in multiple formats including plain text delimited such as CSV, JSON and ODATA. The data includes a single row of headers information indicating the information in the column. These column headers will either be in a human readable header that may be translated or in a single, short form which is not translated. The short form is typically used for Weather API usage to make it easier to consume the data. When using the Weather API, the shortColumnNames parameters indicates whether or not short column names will be used.

Hourly and Daily Dataset Aggregation

All data within the a system is calculated at the hourly data level for accuracy and consistency. When requests are made for longer time periods, such as daily weather forecast or monthly historical summaries, the hourly data is aggregated using average (mean), sum, minimum or maximum functions. The individual column documentation below explains the aggregation method used.

Unit group

The units of the data are specified by the overal unit group requests such as metric, US units etc. This unit group defines the unit of measure used for each column type – all columns of the same variable type will have the same unit. For example, celcius will be used for all temperature related quantities when the unit group is set to metric.

Common columns

Data sets will typically include information about the location, period or data time. If the requested data includes address, the address information is included in the return value. In addition, the latitude and longitude of the requested locations are returned using decimals degrees. The longitude value are zero based at the prime meridian. Values west of the prime meridian are negative and east are positive.

For more information on how dates and times are returned in the Weather API results, see Dates and Times in the Weather API.

Empty values

Empty values (or null values) are used within the data set to indicate an absence of data, such as missing weather information or unknown data. They are not used to indicate a zero value. For example, an unknown precipitation value will be marked as empty or null. A zero amount of precipitation will be indicated by the value zero.

Weather element availability

We aim to include all weather elements such as temperature, wind, precipitation etc for all locations. Unfortunately not all locations report all weather elements. In those cases the columns will be included in the data but include null values. We continue to expand the availabilty of weather elements as we add additional data sets and data processing.

Core weather columns

These columns are common to most weather data sets including forecast, historical observations and historical summaries. The API setting of ‘shortColumnNames’ when set to true will utilize the column names found below in parenthesis. (&shortColumnNames=true)

Temperature (temp, mint, maxt)

There are three main columns for indicating temperature – Minimum Temperature, Maximum Temperature and Temperature. These will return data in Fahrenheit, Celsius or Kelvin depending on the unit group. The three temperature columns indicate the minimum, maximum and average (mean) temperature for the time period in question. For example, if you request daily data then you will receive the data for minimum, maximum and mean temperature for each day. If you request data for the shortest available timeframe for that request (typically one hour), the minimum, maximum and mean are returned with the same value. All data sets will include all three columns even if the values are the same to ease consumption of the data sets and keep data set consistency.

Wind (wspd, wdir, wgust)

Wind data includes wind speed, wind gust and wind direction.

Wind speed and wind direction (wspd, wdir)

The wind speed and wind direction indicate the maximum wind speed for the location and time period requested. The units of the data will be in miles per hour, kilometers per hour or m/s depending on the unit group.

Wind speed is typically measured 10m above ground in a location with no nearby obstructions.

The wind direction indicates the direction from where the wind is blowing from. The units of the wind direction is degrees from north. The value ranges from 0 degrees (from the North), to 90 degrees (from the east), 180 degrees (from the south), 270 (from the west) back to 360 degrees.

Wind gust (wgust)

Wind gust is the maximum wind speed measures over a short amount of time (typically less than 20 seconds). Note that a wind gust requires the measured short term wind speed to be significantly more than mean wind speed. Typically, the wind speed should be 10 knots more (11mph or 18kph). When the wind gust does not meet these criteria, a null/empty value is returned.

The wind direction indicates the direction from where the wind is blowing from. The units of the wind direction is degrees from north. The value ranges from 0 degrees (from the North), to 90 degrees (from the east), 180 degrees (from the south), 270 (from the west) back to 360 degrees.

Precipitation (precip, pop)

Precipitation is the sum of the amount of liquid equivalent rainfall, snow or other precipitation that fell is predicted to fall in the period. Three output variables cover precipitation:

Precipitation (precip)

The amount of precipitation that fell or is predicted to fall in the specified time period. The values are indicated in inches or mm.

Chance of precipitation (pop)

The possibility of precipitation for the given time period expressed as a percentage change from 0-100%. This applies to the forecast queries only.

Precipitation Coverage

This is the proportion of time for which measurable precipitation was record during the time period, expressed as a percentage. For example, if within a 24 hour day there are six hours of measurable rainfall, the precipitation coverage is 25% (6/24*100). This information is only available for historical weather observation data and historical summaries. Note that where as trace precipitation is considered zero value for the precipitation column, a trace precipitation report will be considered as precipitation for the precipitation coverage column. Therefore it is possible to observe zero reported precipitation with a non-zero precipitation coverage.

Precipitation Type (preciptype )

(Forecast only) Provides the type(s) of precipitation expected. Possible values include rain, snow, freezing rain and ice.

Cloud cover (cloudcover)

Cloud cover is the amount of sky that is covered by cloud expressed as a percentage. The cloud coverage is for all altitudes. Daily values include the mean of the hourly cloud coverage values.

Snow and Snow Depth (snow, snowdepth)

Snow is the amount of new snow that has fallen in the time period. Snow depth is the average amount of snow currently on the ground for the time period. Snow depth will increase with additional snowfall and decrease with melting and compaction. Both snow and snow depth are expressed in inches or centimeters.

Relative Humidity, Heat Index and Wind Chill (humidity, heatindex, windchill)

Relative humidity (humidity)

Relative humidity the amount of water vapor present in the air compared the maximum amount possible for a given temperature, expressed as a mean percentage. Human comfort levels are typically found between 30-70%. Values higher than 70% are considered humid. Values lower than 30% are considered dry.

Heat Index (heatindex)

Heat Index is a measure of how hot it feels combining the actual air temperature with the relative humidity. High humidity is associated with discomfort by making the apparent temperature hotter than it would otherwise feel. Values are expressed in the same units as temperature. Heat index values are only calculated when the temperature is greater than 80F (about 26.7C) and the relative humidity is greater than 40%. An empty value is returned outside of these ranges.

Wind chill (windchill)

Wind chill is the measure of how cold it feels combining the actual air temperature with the wind speed. Wind makes temperatures feel colder than when the air is still. Values are expressed in the same units as temperature. Wind chill values are only calculated when the temperature is less than 50F (about 10C) and the wind speed is greater than 3mph (5kph). An empty value is returned outside of these ranges.

Visibility

Visibility is the distance than can be seen in daylight. This account of weather phenomenon such as haze, mist, fog or smoke. The distance is expressed in miles or kilometers.

Sea Level Pressure (sealevelpressure)

The atmospheric pressure at a location that removes reduction in pressure due to the altitude of the location. This is expressed in millibars.

Solar radiation and energy

Solar radiation and solar energy are available in the forecast and historical observations datasets. The solar radiation measures the power (in W/m2) at the instantaneous moment of the observation (or forecast prediction). The solar energy(in 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.

Weather Type (conditions)

Notable weather conditions reported at a particular location such as any thunderstorms, rainfall etc. The availability of this data is dependent on the weather station that observed the information and is not reported by all weather stations – the absence of a particular weather type should not be considered evidence that the weather type did not occur. See Weather Data Conditions for more information.

Astronomical information

Astronomical information may optionally be included in the weather forecast, current conditions and historical weather data record output. To include the astronomical information, use the includeAstronomy=true parameter in the API request.

Sunset & sunrise

The time of the sunrise and sunset for the date and location in question. Times are given in the local time zone.

Moonphase

A decimal value representing the current moon phase between 0 and 1 where 0 represents the new moon, 0.5 represents the full moon. The full cycle can be represented as:

  • 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

Info

A general information column that may include text based notes such as absence of data for a particular weather station.

Contributing Stations

For historical observations, indicates the weather stations that were used for creating the observation. This is a list of weather station names, their ID within the Visual Crossing weather data platform and the distance from the requested location to the weather station. For more information on how weather station data is combined, please read more.

Historical Weather Summary Daily Statistics

Historical weather summaries include above weather data columns. In addition, Historical Weather Summary data sets can optionally include detailed daily statistics which provides additional information about the daily values within the data set. This helps identify the typical weather that was experience in the time period rather than extremes.

The daily statistics analyzes the values across the days including also the maximum, minimum and mean and other distribution statistics for each day.

For example if we would like to understand what is the typical daily high temperature for a particular location we can use the the daily statistics. The daily statistics will include the maximum daily high temperature, the mean daily high temperature and the minimum daily high temperature. The maximum daily high temperature will match the maximum high temperature column found in the summary data set. The average maximum temperature will better match our interest for the typical high temperature. The maximum and minimum values highlight the extremes.

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.

If you think you see wrong data, please read through our article on how to tell us so we can investigate and fix problems ASAP!

14 Replies to “Weather Data Documentation”

  1. Does ‘snow depth’ show the average amount of snow on the ground for that day’s time period, or can that ‘average amount’ span multiple days?

    1. Thank you for your question. Snow depth is measured hourly by most weather stations. For longer periods of time (such as daily periods), we return the average amount for all the hours in that day.Historical summaries that longer periods such as weeks or months will also use the average amount.

      Regards
      Visual Crossing Support

  2. Good day,

    Can I check if data for certain areas are restricted or only available in paid subscriptions? Tried extracting the data for various points in Brazil (using specific longitude/latitude coordinates) and the precipitation data were all indicated as “0” except for 1 date – which shouldn’t be the case. Or is this a limitation from the source where the data is obtained from.

    Appreciate the help!

  3. Hi Visual Crossing,

    Do you have data on the global solar radiation as well? I have been searching a lot on this, but have not been able to find anyone yet, that provides forecasts on the global solar radiation. Is this not a usual parameter to forecast from a meteorological point of view?

    Cheers!

    1. Thank you for the question.

      We are currently rolling out solar radiation data. It is currently available in the standard 15-day forecast results if you enable ‘Show all columns’. For API queries, you need to set the dataElements parameter to ‘all’ (ie &dataElements=all) to retrieve the Solar Radiation column. We will rolling out the solar radiation for historical datasets in the near future. If you would like an update, please email support@visualcrossing.com to be put on the notification list for when this is released.

      Regards
      Visual Crossing Support

    1. The weather forecasts are updated throughout the day based on the combination of multiple weather forecast models. In many places, such as North America and Europe, multiple models are used to combine the higher accuracy shorter term local models with the long term models such as the GFS model. In most locations this means the forecast is updated approximately every three hours.

      For more information, see How do we create our multi-location weather forecast?.

      Regards
      Visual Crossing Support

  4. Hi VisualCrossing

    Will you provide some variables relating to AIQ? Copernicus keeps aggregating indecies of aerosols and chemicals on S3 Amazon forming a huge retrospective data lake. Covid19 enforces more exigent need of air quality in some metros.

    Thank you.

  5. Is there a list of all the possible conditions (historical weather) and icons (forecast information). I need to map these to enumerated types for calculation purposes. (i.e. clear, rain, cloudy, partly-cloudy, etc.)

    1. Eric

      Thank you for your email. The list of icons is available in the following article: Defining the icon set parameter in the Weather API.

      The conditions field is documented here: Weather Data Conditions. If you are looking to access the information programmatically, we recommend you request the ‘id’ version of the language parameter as this will not change if we make corrections or improvements to our translations.

      You can find the full list of current weather conditions in the language files on our public repository.

      Regards
      Visual Crossing Support

  6. I’m using the API to retrieve the hourly values for the previous day. In the API query string there is a parameter called ‘dataElements’ set to a value of ‘default’.

    On the web page to test a particular query string, there is a checkbox labelled ‘Show all columns.’

    Are these 2 items somehow related? When I run the query and get output, I see a particular set of columns. When I click the checkbox, additional columns are added to the display.

    Can I get all those columns via the API? Is that controlled by the ‘dataElements’ parameter? What are the permitted values for ‘dataElements?’

    Thanks in advance

    1. Thank you for your question. The checkbox ‘show all columns’ are different settings. The ‘show all columns’ is a UI feature to hide some lesser used columns. To request the full set of columns, use dataElements=all. The full set of dataElement values are ‘legacy’, ‘default’ and ‘all’.

      It’s a little confusing but ‘legacy’ is the option used if no option is specified at all. This is keep column compatibility for clients that have a usage where the number of columns or column order change would break compatibility. If you do write a script against ‘all’ please ensure that it able to handle a change in the order of the columns or additional columns.

      Regards
      Visual Crossing Support

Comments are closed.