1. WeatherPlanner

    WeatherPlanner is a planning tool that provides long range weather forecasts, providing a proven, reliable view of the weather up to a year in advance.
    WeatherPlanner currently provides forecasts for the US and Canada. We are working on the rest of the world.

     

 

Documentation


How to use the WeatherPlanner Forecast API

This will be a brief tutorial on using the WeatherPlanner API.

Each request to the API will return a JSON result, to interpret the results please see the results section below. But first lets look at the request.

WeatherPlanner Forecast API

https://weatherplanner.azure-api.net/v1/Forecast/{Location}/{StartMonth}/{StartDay}/{StartYear}/{EndMonth}/{EndDay}/{EndYear}?subscription-key=<Your subscription key>

Parameters

  All parameters are required, there are no default values
Location* string Location name
  Please note: USA locations should not include ", USA" or " USA"
  Start date must be today or greater.
StartMonth* number Forecast Start Month (mm)
StartDay* number Forecast Start Day (dd)
StartYear* number Forecast Start Year (yyyy)
  End date must be the start date or greater and at most 1 year into the future.
EndMonth* number Forecast End Month (mm)
EndDay* number Forecast End Day (dd)
EndYear* number Forecast End Year (yyyy)

Back to top


How to use the WeatherPlanner Geo API

This will be a brief tutorial on using the WeatherPlanner API.

Each request to the API will return a JSON result, to interpret the results please see the results section below. But first lets look at the request.

WeatherPlanner Geo API

https://weatherplanner.azure-api.net/v1/ForecastInterval/geo/{lat}/{lon}/{StartMonth}/{StartDay}/{StartYear}/{NumberOfDays}?subscription-key=<Your subscription key>

Parameters

  All parameters are required, there are no default values
lat* string Location latitude (ex. 38.9444)
lon* string Location longitude (ex. -77.4558)
  Start date must be today or greater.
StartMonth* number Forecast Start Month (mm)
StartDay* number Forecast Start Day (dd)
StartYear* number Forecast Start Year (yyyy)
NumberOfDays* number Number of days to obtain the forecast for (Must not be greater than 30 days)

Back to top


Results

Lets start with the error conditions.

The location specifies the locale for the forecast (currently US and Canadian locations only). The Geo location lookups return the location as "dummy fill"

If WeatherPlanner can not return information for the specified location an error will be returned:
{"status":"location_not_found"}

If WeatherPlanner can not use either of the dates specified, then an error will be returned:
{"status":"date_error","description":"Text describing error"}
The description field will describe the date error encountered.

Should WeatherPlanner encounter an unknown error, this status will be returned:
{"status":"system_error","system_text":"Text describing error"}
The description field will describe the system error.

Next there is the multiple location result, should you supply an ambiguous location, WeatherPlanner will try to return a list of the top matches for this location.

For this example we supplied Manchester for the location, and WeatherPlanner returns this result:
{ "status":"multiple_locations", "locations":{ "top_locations":[ "Manchester,NH", "Manchester,VT", "Manchester,MA", "Manchester,ME" ], "total_number":4 } }

Finally the result that we are looking for is the forecast result:

When the status is returned as success, then we have forecast results
{ "status": "success", "forecast": [ { "max_temp_low": 73, "temp": "warm", "max_temp_high": 78, "precipitation_code": "R2N", "temp_code": "w", "date": "06/22/2013", "precipitation": "Chance of rain" }, { "max_temp_low": 73, "temp": "warm", "max_temp_high": 78, "precipitation_code": "DR2", "temp_code": "w", "date": "06/23/2013", "precipitation": "Generally Dry" }, { "max_temp_low": 60, "temp": "cold", "max_temp_high": 66, "precipitation_code": "DR2", "temp_code": "c", "date": "06/24/2013", "precipitation": "Generally Dry" } ] }

The above example shows data for 6/22/2013, 6/23/2013 and 6/24/2013 for the specified location.
Each day will have the following values: (not in order)
"date", "max_temp_low", "max_temp_high", "temp_code", "temp", "precipitation_code", "precipitation"

Maximum temperature range for this date
max_temp_low = the lowest maximum temp expect for this date
max_temp_high = the highest maximum temp expect for this date

Temperature code of the expected maximum temperature for this date
temp_code = temp
vm = very warm
w = warm
s = seasonal
c = cold
vc = very cold

Minimum temperature range for this date
min_temp_low = the lowest minimum temp expect for this date
min_temp_high = the highest minimum temp expect for this date

Temperature code of the expected minimum temperature for this date
min_temp_code = temp
vm = very warm
w = warm
s = seasonal
c = cold
vc = very cold

Expected precipitation_code for this date
precipitation_code = precipitation
DR2 = Generally dry
R2N = A possibility of continuous rain or drizzle occurring.
R3S = A high probability of continuous rain
RSN = possibility of a rain and snow mixture.
RSS = A high probability of rain and snow
RTN = A possibility of rain and thunderstorms
RTS = A high probability of rain and thunderstorms
S1N = A possibility of snow or snow showers
S1S = A high probability of snow or snow showers

Please see WeatherPlanner example page source for more information

Back to top


WeatherPlanner Icons and Explanations (Tile Set)

This is a general explanation of the graphics used to represent the precipitation types in the WeatherPlanner

Precipitation Icons

Generally dry with a chance of precipitation the day before and the day after.
Generally dry with a chance of precipitation the day before and generally dry the day after.
Generally dry with a chance of precipitation the day before and a high chance of precipitation the day after.
Generally dry with generally dry the day before and a chance of precipitation the day after.
Generally dry with generally dry the day before and a high chance of precipitation the day after.
Generally dry with generally dry the day before and generally dry the day after.
A possibility of continuous rain or drizzle occurring.
A high probability of continuous rain occurring over a large portion of the area
This prediction represents the possibility of a rain and snow mixture.
A high probability of rain and snow with greater amounts of precipitation likely.
A possibility of rain and thunderstorms with greater amounts of precipitation likely.
A high probability of rain and thunderstorms with greater amounts of precipitation likely.
A possibility of snow or snow showers, of shorter duration and with low accumulation amounts.
A high probability of snow or snow showers, covering an extensive portion of the local area. Measurable accumulation expected.
Generally dry with a high chance of precipitation the day before and a chance of precipitation the day after.
Generally dry with a high chance of precipitation the day before and generally dry the day after.
Generally dry with a high chance of precipitation the day before and a high chance of precipitation the day after.

Back to top


Graphic Tiles for use with the WeatherPlanner API

To help your users make sense of the WeatherPlanner API we have two different tile sets for your use. Tiles represent the different weather conditions that WeatherPlanner knows about.

The large tile set:

Download the Large Tiles

And the small tile set.

Download the Small Tiles

Back to top