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.
New to the API? Try the New Timeline Weather API
The New Timeline Weather API offers the easiest way to retrieve historical, forecast and statistical forecast data. It offers daily summaries, hourly detail, current conditions and weather alerts in a single, continuous result.
The Timeline API is perfect for anyone transitioning from the Dark Sky APIs including the forecast and time machine API.
See our full Timeline Weather API documentation.
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=YOURAPIKEYParameters
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=YOURAPIKEYParameters
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.326001Parameters
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.
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.
Thank you for your question. We have created a summary article that summaries the different unit groups: Unit groups and measurement units.
If you have any questions, please let us know!
Regards
Visual Crossing Support
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...
Thank you for your question. All times are local times - both those you pass into the API to request information and the output results.
For more information on how we handle the dates, please see Date and times in the weather API
Regards
Visual Crossing Support
Hi, Is it possible to obtain the text for the "conditions" property in languages other than English?
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
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
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
Hi, is there exist a possibility to retrieve summary weather by hour?
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
Thank you for the answer, I suppose it's related to historical but I need for /historysummary
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
Thank you!
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] => ...........
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
I'm trying to access the API via an ESP8266 board but support for https is poor.
Wondering if there is an http connection available?
Thank you for you question. Unfortunately we do not have an http option available in the API to prevent the exposure of API keys and other information. If you have any suggestions on how we could help assist API access via the ESP8266 we'd love to hear about them.
Regards
Visual Crossing Support
Hi VisualCrossing
I encounter the error when invoking :
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/38.906655%2C-77.027269/2020-12-17&key=DQXPXNP3KENRZGWHZNFH8E794
"No session found with id 'null'. The session may have expired"
How can I get a session ID ?
Thank you.
Tommy
Thank you for your question. The API Key parameter should be part of the GET parameters of the request. The & should be replaced with a ? to denote the start of the parameters (if you add additional parameters they should be separated by &).
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/38.906655%2C-77.027269/2020-12-17?key=DQXPXNP3KENRZGWHZNFH8E794
Regards
Visual Crossing Support
Hello,
Following @Ravindra Rao's question, could you list exhaustively the full range of conditions so that we can add them to our translator module?
Regards,
We appreciate your services.
Benoit
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. We do offer a program of free credits if you are willing to add new languages that we can share amongst our users. Please contact support at support@visualcrossing.com for more information on that program.
Regards
Visual Crossing Support
I'm trying to us the /history endpoint, to retreive fairly recent data (it may be several days, or it may be just a few minutes). It seems that if I choose a date which is too close to the current time, then I receive "No data available"
An example request is:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/history?location=,&startDateTime=2021-01-09T10:00:00&endDateTime=2021-01-09T10:00:00&aggregateHours=24&unitGroup=metric&shortColumnNames=false&contentType=json&timezone=Z&key=
If this request is made at, for example, 10:15:00, then I receive no data.
What is the minimum timestamp difference I need for historic data?
Wayne
Thank you for your question. For single row requests, you will typically want to match your aggregateHours or aggregateMinutes setting to the timestamp difference.
For example, if you are using aggregateHours=1 (ie hourly data), your request should be typically rounding to an hour.
If you are using aggregateMinutes=15 (ie every 15 minute data) then you can use a smaller range.
Regards
Visual Crossing Support
I don't think I have access to aggregateMinutes, as I'm using a free account.
Essentially, I have a script which currently uses the DarkSky API to retrieve weather information for an exercise, picking the mid-point of the start/end times, to retrieve the weather there. Depending on when the exercise is uploaded from the watch, it may be a few minutes after completion, or a few days
(As an aside... my script currently uses Dark Sky, and I'm testing out alternatives, including Visual Crossing)
Wayne
I think the Timeline Weather API may be more suited to your request as you can request the weather for a particlar how with a query such as:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/KIAD/2021-01-11T10:00:00?unitGroup=us&key=YOUR_API_KEY
When the time requested is in the past, the 'currentConditions' field will be populated with the historical conditions for the time requested.
Regards
Visual Crossing Support
What is the spatial resolution available for this product?
I understand that it will vary by geography due to the resolution of the underlying NWP model output, so please provide
Thank you for your question. We combine multiple weather forecast models to create our weather forecast. The resolution of the forecast model varies based on the model and also on the time into the future (some models have lower resolution beyond 7-10 days). The resolution is typically 5-10miles. See How do we create our weather forecast? for more information.
Regards
Visual Crossing Support