The Visual Crossing Weather API is a rich, restful API that you can use to get historical weather data, weather forecast data and even climate data sets into your database, analysis tool or coding project. The API has a rich set of parameters that may be overwhelming at first. In this blog, i describe the five most common API calls and how you can use them right now.
Before you can use the samples below, you’ll need an API key. To sign up for a free key, head over to our pricing page and sign up for the plan that fits your needs.
1. Request the weather forecast for a single location
Probably the simplest thing you need to do is retrieve the weather forecast for a single location. Here’s the request for the data for a 15 day forecast for New York City, NY, USA
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/forecast? aggregateHours=24&contentType=csv&unitGroup=us&key=YOUR_API_KEY&locations=New York City,NY
Want the weather for somewhere else? Just replace “New York City,NY” with the address or partial address of the location you want. Remember to encode the URL if your application doesn’t do that for you automatically!
This returns the weather forecast in a simple to read CSV format. You can use this to load the data into many applications including databases, Excel, Power BI and many other BI tools.
Address,Date time,Latitude,Longitude,Resolved Address,Name,Wind Direction,Minimum Temperature,Maximum Temperature,Temperature,Wind Speed,Cloud Cover,Heat Index,Chance Precipitation (%),Precipitation,Sea Level Pressure,Snow Depth,Snow,Relative Humidity,Wind Gust,Wind Chill,Conditions "New York City, NY","08/13/2020",40.7146,-74.0071,"New York City, NY","New York City, NY",140,74.9,76,75.5,1.1,83,,9,0,1017,0,0,80.5,4.7,,"Overcast"
Latitude and longitude
If you have latitude and longitude rather than address, you can easily modify the above request to request a latitude longitude location. In this case, the location is specified using latitude,longitude where the latitude and longitude are in decimal degrees.
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/forecast? aggregateHours=24&contentType=csv&unitGroup=us&key=YOUR_API_KEY&locations=40.7146,-74.0071
2. Request the historical weather conditions for a single location
Once you have the weather forecast for a location, it’s natural to wonder what happened in the past. To retrieve the past weather observations, the request is just as simple:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/history?aggregateHours=24&startDateTime=2020-08-06T00:00:00&endDateTime=2020-08-13T00:00:00&contentType=csv&unitGroup=us&locationMode=single&key= YOUR_API_KEY&locations=New York City,NY
In addition to the location parameter, two more parameters specify the dates you want to retrieve data for – startDateTime and endDateTime.
The data is returned in the same format as the weather forecast so you can easily incorporate the data into the same tools, databases and code as the weather forecast:
Address,Date time,Latitude,Longitude,Resolved Address,Name,Wind Direction,Minimum Temperature,Maximum Temperature,Temperature,Wind Speed,Cloud Cover,Heat Index,Chance Precipitation (%),Precipitation,Sea Level Pressure,Snow Depth,Snow,Relative Humidity,Wind Gust,Wind Chill,Conditions "New York City, NY","08/13/2020",40.7146,-74.0071,"New York City, NY","New York City, NY",140,74.9,76,75.5,1.1,83,,9,0,1017,0,0,80.5,4.7,,"Overcast"
3. Request the monthly climate data for the last 30 years
If you need to know what the weather is normally like at a particular location, the historical summaries provide climate level data of what you can except for any year, month, week or even day throughout the year.
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/historysummary?&minYear=1989&maxYear=2019&chronoUnit=months&breakBy=self&dailySummaries=false&contentType=csv&unitGroup=us&key=YOUR_API_KEY&locations=New York City,NY
The results are CSV again and provide a monthly climate for New York City. If you want to change between yearly, monthly or weekly summaries, change the ‘chronoUnit’ parameter. If you want to break by years, change breakBy=self to breakBy=years
Period,Address,Date time,Minimum Temperature,Maximum Temperature,Temperature,Dew Point,Relative Humidity,Heat Index,Wind Speed,Wind Gust,Wind Direction,Wind Chill,Precipitation,Precipitation Cover,Snow Depth,Visibility,Cloud Cover,Sea Level Pressure "Jan","New York City, NY","",-2.6,70.3,33.8,21.4,62.01,,39.5,56.5,225.36,-24,114.29,9.98,4.7,1,42.4,1017.9 "Feb","New York City, NY","",0.2,72.4,35.5,21.3,58.62,,33.6,57.5,220.22,-19.5,80.64,8.97,4.5,1,39.4,1017.4
4. Request the hourly weather forecast or weather history data
The first two requests requested data by day. What happens if you want the weather forecast by hour? The historical weather data by hour? That’s simple the same requests as above but we change the aggregateHour parameter to 1 rather than 24:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/forecast? aggregateHours=1&contentType=csv&unitGroup=us&key=YOUR_API_KEY&locations=New York City,NY https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/history?aggregateHours=1&startDateTime=2020-08-06T00:00:00&endDateTime=2020-08-13T00:00:00&contentType=csv&unitGroup=us&key= YOUR_API_KEY&locations=New York City,NY
That’s all that’s required – now the data is available for every hour. You can even request data down to the minute, depending on your plan.
5. Request the results in JSON for easy programing
If you are familiar with coding in Javascript, or you’re moving from another API such as the defunct Dark Sky API, you can request the data in JSON format. This makes it easy to integrate into many coding environments. You can do this with any of the above requests with a single API parameter switch:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/forecast? aggregateHours=1&contentType=json&unitGroup=us&key=YOUR_API_KEY&locations=New York City,NY https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/history?aggregateHours=1&startDateTime=2020-08-06T00:00:00&endDateTime=2020-08-13T00:00:00&contentType=json&unitGroup=us&key= YOUR_API_KEY&locations=New York City,NY
The JSON output is really easy to use and integrate into your application. For full information on the JSON structure, check out the JSON structure documentation.
The JSON format allows even more great features – for example the forecast data you retrieve will include the forecast and also the current conditions.
Next steps
The examples above show how easy it is to get weather data from a weather API. If you would like more information, check out the API documentation.
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.