API Documentation v1.0

This document assumes you already have a valid key that grants you access to this API. If you don't yet have one, head over to our site and fill out the API Access Request Form. We have varying levels of access available but you can certainly just request a free key and give it all a whirl. So let's pretend that's all out of the way. It all begins with this:

http://api.weather2020.com/YOURAPIKEY/LATITUDE,LONGITUDE


Feel free to use the latitude/longitude pair of 39.09972,-94.57856 to get a quick start. That will get you the forecasts for Kansas City, MO. But please note, if you're using a free account you'll be limited to lat/long pairs within your chosen zip code bounds. So get yourself a valid lat/long pair to go with your valid API key, build the URL, and paste it right in your browser to see a live response. Nothing fancy required.

When a successful API call is made, a JSON formatted array of weekly forecast objects is returned. Depending on your key type the size of that array will either be 4 or 12 weeks in length. Each of those forecast objects contain the data listed below.

regionAffected
The region associated with the latitude and longitude provided in the API call.
headline
Brief summary of the weeks forecasted conditions. Typically one or two short sentences. Please note there is not currently a limit on number of characters allowed.
forecastDesc
This is where the bulk of the information will reside. This is a brief paragraph giving an overview of weather events throughout the week and will often emphasize conditions around certain landmarks and/or well-populated cities in the region. Expect a decent number of characters here and note that the length is not currently limited.
startDate
This is the epoch time (in seconds...obviously) of Sunday at 12:00:00AM UTC for this week.
revision
This signifies the number of times any of the fields have been edited. A revision could simply be fixing a typo or a tweaking of the forecast by our team of meteorologists based on new cycle data. Regardless of the edit it can be used to know if you have stale data.
events
[ ] - An array of event objects. This is not currently used and henceforth somewhat of a placeholder. We are exploring our options to determine the best way to utilize this event data. But with that said, when used each event object will currently contain the data below.
title
Obviously the pretty formatted name of the event.
slug
A "slugified" version of the title. Could be used for internal mapping to custom graphic/icon.
type
This could be national holiday, sporting event, solar eclipse.
date
TBD - Likely be epoch time of the event's start time (UTC).
icon
A full and valid URL to the event icon.
conditions
[ ] - An array of condition objects each containing the data below. Please note that if you're limited in space and want to show only one condition, our team of meteorologists select the first condition as the most prominent for the week. So be sure to use array index position [0]. If you want to delve ever so slightly into the topic of summing 7 days of weather into one tidbit feel free to check out the Philosophy below. Also, a full list of our possible conditions live at the bottom of this page.
display
A pretty formatted text explanation of the condition.
tag
A "slugified" version of the condition. Might be useful for mapping to pretty icons representing specific weather conditions. I dunno just a friendly suggestion...
forecastLengthInHours
For now will always be 168. So that's 7 days * 24 hours. In the future this may be used to make short targeted forecasts for specific events. But for now it's mostly a placeholder.
temperatureHigh
This is the approximate high temperature that will occur during the week. This is specific to the latitude and longitude provided in the call. Temperature is in Fahrenheit.
temperatureLow
Same as the above except the approximate low temperature for the week.
temperatureHighCelcius
Just like above except conveniently converted to Celcius.
temperatureLowCelcius
Blah blah blah...you know the deal.

12 Week Weather Forecast API Philosophy

As general walkers of the Earth, weather enthusiasts, and/or potentially avid consumers of API data, it may be hard to shake the expectation that all forecasting should be purely numerical pieces of data meant to tell you the exact measurement of temperature and precipitation for a single moment in time. Our forecasts aren't meant to tell you that it will rain precisely one half inch with the wind blowing at 9mph on Thursday at 9:34AM at a specific street crossing in Detroit. Now this doesn't necessary preclude the possibility of getting somewhat specific in week's forecast description. But that just shouldn't be your consistent expectation with this API data. It's meant more as a broad overview of what's coming to give you an advantage in whatever decision making processes in which you may be involved.

Full List Of Possible Conditions

{
    'blowing-dust': 'Blowing Dust',
    'blowing-snow': 'Blowing Snow',
    'clear': 'Clear',
    'drifting-snow': 'Drifting Snow',
    'drizzle': 'Drizzle',
    'dust-storm': 'Dust Storm',
    'fog': 'Fog',
    'freezing-drizzle': 'Freezing Drizzle',
    'freezing-fog': 'Freezing Fog',
    'freezing-rain': 'Freezing Rain',
    'hail': 'Hail',
    'haze': 'Haze',
    'heavy-drizzle': 'Heavy Drizzle',
    'heavy-rain': 'Heavy Rain',
    'heavy-snow': 'Heavy Snow',
    'heavy-thunderstorm': 'Heavy Thunderstorm',
    'light-drizzle': 'Light Drizzle',
    'light-fog': 'Light Fog',
    'light-freezing-drizzle': 'Light Freezing Drizzle',
    'light-freezing-rain': 'Light Freezing Rain',
    'light-hail': 'Light Hail',
    'light-rain': 'Light Rain',
    'light-rain-and-snow': 'Light Rain and Snow',
    'light-rain-and-snow-shower': 'Light Rain and Snow Shower',
    'light-rain-shower': 'Light Rain Shower',
    'light-snow': 'Light Snow',
    'light-snow-shower': 'Light Snow Shower',
    'mostly-clear': 'Mostly Clear',
    'mostly-cloudy': 'Mostly Cloudy',
    'overcast': 'Overcast',
    'partly-cloudy': 'Partly Cloudy',
    'patchy-fog': 'Patchy Fog',
    'rain': 'Rain',
    'rain-and-snow': 'Rain and Snow',
    'rain-and-snow-shower': 'Rain and Snow Shower',
    'rain-shower': 'Rain Shower',
    'severe-dust-storm': 'Severe Dust Storm',
    'sleet': 'Sleet',
    'smoke': 'Smoke',
    'snow': 'Snow',
    'snow-shower': 'Snow Shower',
    'squall': 'Squall',
    'thunderstorm': 'Thunderstorm'
  }