Introduction
Welcome to the Weather 20/20 API! You can use our API to access our weather forecasts.
This API is available only to Weather 20/20's clients. If you are not a client and are interested in using this API, please contact us.
Authentication
To authorize requests, use this code:
# With shell, you can just pass the correct header with each request
curl "https://api.weather2020.com/forecasts?lat=42.0&lon=42.0&start_date=2021-08-01&end_date=2021-09-01" \
-H "X-API-Key: tickettoweatherintelligence"
Make sure to replace
tickettoweatherintelligencewith your API key.
Weather 20/20 uses API keys to allow clients to access to our API. If you're a new client, contact us to create a trial plan.
Please include your API key in all API requests in the X-API-Key header.
Please see the example to the right.
Rate Limits
Each plan has a daily and secondly rate limit.
If either is exceeded, the server responds with the 429 status code.
The daily rate limit resets every midnight in UTC time.
Requests spanning more than one month count as multiple requests toward your daily and secondly quotas. For example, a request from 2021-01-01 to 2021-02-01 counts as a single request. A request from 2021-01-01 to 2021-02-02 counts as two requests, since we round up.
Our API sets the following headers on each response:
Rate Limit Headers
| Name | Description |
|---|---|
X-RateLimit-Limit |
The maximum number of requests you can send per day |
X-RateLimit-Reset |
The time at which the current rate limit window resets in UTC epoch seconds |
X-RateLimit-Remaining |
The number of requests you can make before X-RateLimit-Reset |
Endpoints
List Forecasts
curl "https://api.weather2020.com/forecasts?lat=42&lon=42&units=metric&end_date=2021-11-30&start_date=2021-11-23" \
-H "Authorization: tickettoweatherintelligence"
The above request returns forecasts for Georgia (the country):
{
"data": [
{
"cc": 74.9,
"date": "2021-11-23",
"dewpt": 4.64,
"max_wind_spd": 3.96,
"prcp": 5.17,
"rh": 74.9,
"slp": 1022.82,
"snow": 0.21,
"sp": 997.35,
"temp": 8.85,
"tmax": 13.1,
"tmin": 6.09,
"wind_dir": 147.55,
"wind_spd": 2.49
},
{
"cc": 72.3,
"date": "2021-11-24",
"dewpt": 3.92,
"max_wind_spd": 2.5,
"prcp": 0.0,
"rh": 72.3,
"slp": 1024.75,
"snow": 0.18,
"sp": 999.23,
"temp": 8.63,
"tmax": 13.82,
"tmin": 4.88,
"wind_dir": 105.68,
"wind_spd": 1.86
},
{
"cc": 71.5,
"date": "2021-11-25",
"dewpt": 3.73,
"max_wind_spd": 3.16,
"prcp": 0.0,
"rh": 71.5,
"slp": 1023.49,
"snow": 0.37,
"sp": 998.01,
"temp": 8.6,
"tmax": 13.61,
"tmin": 4.75,
"wind_dir": 126.49,
"wind_spd": 2.06
},
{
"cc": 73.0,
"date": "2021-11-26",
"dewpt": 4.24,
"max_wind_spd": 3.15,
"prcp": 2.3,
"rh": 73.0,
"slp": 1022.67,
"snow": 0.0,
"sp": 997.17,
"temp": 8.81,
"tmax": 13.79,
"tmin": 4.98,
"wind_dir": 153.29,
"wind_spd": 1.95
},
{
"cc": 71.5,
"date": "2021-11-27",
"dewpt": 4.74,
"max_wind_spd": 3.04,
"prcp": 2.7,
"rh": 71.5,
"slp": 1020.8,
"snow": 0.1,
"sp": 995.43,
"temp": 9.65,
"tmax": 14.99,
"tmin": 5.1,
"wind_dir": 126.23,
"wind_spd": 2.01
},
{
"cc": 77.1,
"date": "2021-11-28",
"dewpt": 6.19,
"max_wind_spd": 2.66,
"prcp": 5.93,
"rh": 77.1,
"slp": 1021.61,
"snow": 0.37,
"sp": 996.17,
"temp": 10.02,
"tmax": 14.63,
"tmin": 6.07,
"wind_dir": 148.26,
"wind_spd": 1.64
},
{
"cc": 78.4,
"date": "2021-11-29",
"dewpt": 6.24,
"max_wind_spd": 2.99,
"prcp": 9.31,
"rh": 78.4,
"slp": 1020.54,
"snow": 0.37,
"sp": 995.14,
"temp": 9.83,
"tmax": 14.4,
"tmin": 6.69,
"wind_dir": 140.79,
"wind_spd": 1.7
}
]
}
curl "https://api.weather2020.com/forecasts?units=imperial&end_date=2021-11-30&start_date=2021-11-23&postal_code=46774" \
-H "Authorization: tickettoweatherintelligence"
The above request returns forecasts for Fort Wayne, Indiana using imperial units:
{
"data": [
{
"cc": 64.1,
"date": "2021-11-23",
"dewpt": 34.15,
"max_wind_spd": 13.45,
"prcp": 0.0,
"rh": 64.1,
"slp": 1019.19,
"snow": 0.01,
"sp": 989.47,
"temp": 45.58,
"tmax": 52.65,
"tmin": 38.98,
"wind_dir": 241.27,
"wind_spd": 9.33
},
{
"cc": 66.8,
"date": "2021-11-24",
"dewpt": 32.03,
"max_wind_spd": 13.03,
"prcp": 0.03,
"rh": 66.8,
"slp": 1020.24,
"snow": 0.01,
"sp": 990.38,
"temp": 42.26,
"tmax": 53.04,
"tmin": 36.05,
"wind_dir": 226.05,
"wind_spd": 8.86
},
{
"cc": 65.7,
"date": "2021-11-25",
"dewpt": 34.04,
"max_wind_spd": 17.32,
"prcp": 0.19,
"rh": 65.7,
"slp": 1016.71,
"snow": 0.06,
"sp": 987.06,
"temp": 44.81,
"tmax": 51.43,
"tmin": 39.64,
"wind_dir": 214.75,
"wind_spd": 12.13
},
{
"cc": 72.3,
"date": "2021-11-26",
"dewpt": 35.94,
"max_wind_spd": 13.05,
"prcp": 0.19,
"rh": 72.3,
"slp": 1015.52,
"snow": 0.0,
"sp": 985.93,
"temp": 44.31,
"tmax": 50.22,
"tmin": 38.83,
"wind_dir": 252.09,
"wind_spd": 9.48
},
{
"cc": 75.2,
"date": "2021-11-27",
"dewpt": 35.58,
"max_wind_spd": 12.53,
"prcp": 0.11,
"rh": 75.2,
"slp": 1016.58,
"snow": 0.02,
"sp": 986.91,
"temp": 42.89,
"tmax": 50.24,
"tmin": 36.93,
"wind_dir": 207.15,
"wind_spd": 8.45
},
{
"cc": 81.0,
"date": "2021-11-28",
"dewpt": 36.14,
"max_wind_spd": 14.9,
"prcp": 0.23,
"rh": 81.0,
"slp": 1018.08,
"snow": 0.0,
"sp": 988.24,
"temp": 41.55,
"tmax": 50.0,
"tmin": 36.19,
"wind_dir": 224.56,
"wind_spd": 10.47
},
{
"cc": 71.3,
"date": "2021-11-29",
"dewpt": 33.59,
"max_wind_spd": 14.27,
"prcp": 0.1,
"rh": 71.3,
"slp": 1021.37,
"snow": 0.03,
"sp": 991.41,
"temp": 42.22,
"tmax": 49.69,
"tmin": 35.62,
"wind_dir": 227.39,
"wind_spd": 10.09
}
]
}
This endpoint retrieves daily forecasts for a single location over a date range.
Forecasts are available for the entire world up to 180 days out.
Users must specify either latitude and longitude or postal code and (optionally) a country code.
HTTP Request
GET https://api.weather2020.com/forecasts
Query Parameters
| Parameter | Description |
|---|---|
| start_date | Inclusive start date of the interval to retrieve in YYYY-MM-DD format |
| end_date | Exclusive end date of the interval to retrieve in YYYY-MM-DD format |
| lat | Latitude of the location to retrieve |
| lon | Longitude of the location to retrieve |
| postal_code | Postal code to retrieve data for. For the United States, the 5-digit postal code should be used. |
| country | [optional] ISO-2 country code of the country to fetch data for. Used iff postal code is specified. The default is US. |
| units | [optional] Unit system to use. The choices are metric and imperial. The default is metric. |
Response Structure
These are the fields of each element in the data field of the response.
| Field | Metric (default) | Imperial | Description |
|---|---|---|---|
| date | Gregorian | Gregorian | Date forecasted in YYYY-MM-DD format. This date is in UTC time. |
| prcp | mm | inches | Liquid-equivalent precipitation |
| snow | mm | inches | Liquid-equivalent snow precipitation |
| tmax | C˚ | F˚ | High temperature |
| tmin | C˚ | F˚ | Low temperature |
| temp | C˚ | F˚ | Average temperature |
| dewpt | C˚ | F˚ | Average dewpoint temperature |
| wind_spd | m/s | mi/h | Average wind speed |
| max_wind_spd | m/s | mi/h | Maximum wind speed |
| wind_dir | degrees | degrees | Average wind direction |
| rh | % | % | Average relative humidity |
| cc | % | % | Average total cloud coverage |
| slp | mb | mb | Average sea level pressure |
| sp | mb | mb | Average pressure |
List History
curl "https://api.weather2020.com/history?lat=42&lon=42&units=metric&end_date=2021-11-30&start_date=2021-11-23" \
-H "Authorization: tickettoweatherintelligence"
The above request returns history for Georgia (the country):
{
"data": [
{
"cc": 74.9,
"date": "2021-01-23",
"dewpt": 4.64,
"max_wind_spd": 3.96,
"prcp": 5.17,
"rh": 74.9,
"slp": 1022.82,
"snow": 0.21,
"sp": 997.35,
"temp": 8.85,
"tmax": 13.1,
"tmin": 6.09,
"wind_dir": 147.55,
"wind_spd": 2.49
},
{
"cc": 72.3,
"date": "2021-01-24",
"dewpt": 3.92,
"max_wind_spd": 2.5,
"prcp": 0.0,
"rh": 72.3,
"slp": 1024.75,
"snow": 0.18,
"sp": 999.23,
"temp": 8.63,
"tmax": 13.82,
"tmin": 4.88,
"wind_dir": 105.68,
"wind_spd": 1.86
},
{
"cc": 71.5,
"date": "2021-01-25",
"dewpt": 3.73,
"max_wind_spd": 3.16,
"prcp": 0.0,
"rh": 71.5,
"slp": 1023.49,
"snow": 0.37,
"sp": 998.01,
"temp": 8.6,
"tmax": 13.61,
"tmin": 4.75,
"wind_dir": 126.49,
"wind_spd": 2.06
},
{
"cc": 73.0,
"date": "2021-01-26",
"dewpt": 4.24,
"max_wind_spd": 3.15,
"prcp": 2.3,
"rh": 73.0,
"slp": 1022.67,
"snow": 0.0,
"sp": 997.17,
"temp": 8.81,
"tmax": 13.79,
"tmin": 4.98,
"wind_dir": 153.29,
"wind_spd": 1.95
},
{
"cc": 71.5,
"date": "2021-01-27",
"dewpt": 4.74,
"max_wind_spd": 3.04,
"prcp": 2.7,
"rh": 71.5,
"slp": 1020.8,
"snow": 0.1,
"sp": 995.43,
"temp": 9.65,
"tmax": 14.99,
"tmin": 5.1,
"wind_dir": 126.23,
"wind_spd": 2.01
},
{
"cc": 77.1,
"date": "2021-01-28",
"dewpt": 6.19,
"max_wind_spd": 2.66,
"prcp": 5.93,
"rh": 77.1,
"slp": 1021.61,
"snow": 0.37,
"sp": 996.17,
"temp": 10.02,
"tmax": 14.63,
"tmin": 6.07,
"wind_dir": 148.26,
"wind_spd": 1.64
},
{
"cc": 78.4,
"date": "2021-01-29",
"dewpt": 6.24,
"max_wind_spd": 2.99,
"prcp": 9.31,
"rh": 78.4,
"slp": 1020.54,
"snow": 0.37,
"sp": 995.14,
"temp": 9.83,
"tmax": 14.4,
"tmin": 6.69,
"wind_dir": 140.79,
"wind_spd": 1.7
}
]
}
curl "https://api.weather2020.com/history?units=imperial&end_date=2021-01-30&start_date=2021-01-23&postal_code=46774" \
-H "Authorization: tickettoweatherintelligence"
The above request returns history for Fort Wayne, Indiana using imperial units:
{
"data": [
{
"cc": 64.1,
"date": "2021-01-23",
"dewpt": 34.15,
"max_wind_spd": 13.45,
"prcp": 0.0,
"rh": 64.1,
"slp": 1019.19,
"snow": 0.01,
"sp": 989.47,
"temp": 45.58,
"tmax": 52.65,
"tmin": 38.98,
"wind_dir": 241.27,
"wind_spd": 9.33
},
{
"cc": 66.8,
"date": "2021-01-24",
"dewpt": 32.03,
"max_wind_spd": 13.03,
"prcp": 0.03,
"rh": 66.8,
"slp": 1020.24,
"snow": 0.01,
"sp": 990.38,
"temp": 42.26,
"tmax": 53.04,
"tmin": 36.05,
"wind_dir": 226.05,
"wind_spd": 8.86
},
{
"cc": 65.7,
"date": "2021-01-25",
"dewpt": 34.04,
"max_wind_spd": 17.32,
"prcp": 0.19,
"rh": 65.7,
"slp": 1016.71,
"snow": 0.06,
"sp": 987.06,
"temp": 44.81,
"tmax": 51.43,
"tmin": 39.64,
"wind_dir": 214.75,
"wind_spd": 12.13
},
{
"cc": 72.3,
"date": "2021-01-26",
"dewpt": 35.94,
"max_wind_spd": 13.05,
"prcp": 0.19,
"rh": 72.3,
"slp": 1015.52,
"snow": 0.0,
"sp": 985.93,
"temp": 44.31,
"tmax": 50.22,
"tmin": 38.83,
"wind_dir": 252.09,
"wind_spd": 9.48
},
{
"cc": 75.2,
"date": "2021-01-27",
"dewpt": 35.58,
"max_wind_spd": 12.53,
"prcp": 0.11,
"rh": 75.2,
"slp": 1016.58,
"snow": 0.02,
"sp": 986.91,
"temp": 42.89,
"tmax": 50.24,
"tmin": 36.93,
"wind_dir": 207.15,
"wind_spd": 8.45
},
{
"cc": 81.0,
"date": "2021-01-28",
"dewpt": 36.14,
"max_wind_spd": 14.9,
"prcp": 0.23,
"rh": 81.0,
"slp": 1018.08,
"snow": 0.0,
"sp": 988.24,
"temp": 41.55,
"tmax": 50.0,
"tmin": 36.19,
"wind_dir": 224.56,
"wind_spd": 10.47
},
{
"cc": 71.3,
"date": "2021-01-29",
"dewpt": 33.59,
"max_wind_spd": 14.27,
"prcp": 0.1,
"rh": 71.3,
"slp": 1021.37,
"snow": 0.03,
"sp": 991.41,
"temp": 42.22,
"tmax": 49.69,
"tmin": 35.62,
"wind_dir": 227.39,
"wind_spd": 10.09
}
]
}
This endpoint retrieves daily historical data for a single location over a date range.
Users must specify either latitude and longitude or postal code and (optionally) a country code.
HTTP Request
GET https://api.weather2020.com/history
Query Parameters
| Parameter | Description |
|---|---|
| start_date | Inclusive start date of the interval to retrieve in YYYY-MM-DD format |
| end_date | Exclusive end date of the interval to retrieve in YYYY-MM-DD format |
| lat | Latitude of the location to retrieve |
| lon | Longitude of the location to retrieve |
| postal_code | Postal code to retrieve data for. For the United States, the 5-digit postal code should be used. |
| country | [optional] ISO-2 country code of the country to fetch data for. Used iff postal code is specified. The default is US. |
| units | [optional] Unit system to use. The choices are metric and imperial. The default is metric. |
Response Structure
These are the fields of each element in the data field of the response.
| Field | Metric (default) | Imperial | Description |
|---|---|---|---|
| date | Gregorian | Gregorian | Date forecasted in YYYY-MM-DD format. This date is in UTC time. |
| prcp | mm | inches | Liquid-equivalent precipitation |
| snow | mm | inches | Liquid-equivalent snow precipitation |
| tmax | C˚ | F˚ | High temperature |
| tmin | C˚ | F˚ | Low temperature |
| temp | C˚ | F˚ | Average temperature |
| dewpt | C˚ | F˚ | Average dewpoint temperature |
| wind_spd | m/s | mi/h | Average wind speed |
| max_wind_spd | m/s | mi/h | Maximum wind speed |
| wind_dir | degrees | degrees | Average wind direction |
| rh | % | % | Average relative humidity |
| cc | % | % | Average total cloud coverage |
| slp | mb | mb | Average sea level pressure |
| sp | mb | mb | Average pressure |
Errors
The Weather 20/20 API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- The request is invalid. This will always be accompanied by a more detailed error message. |
| 401 | Unauthorized -- The API key is wrong or has been de-activated. Please contact us for a new API key. |
| 403 | Forbidden -- Sorry, you do not have access to the requested product. Please contact us to upgrade your plan. |
| 418 | I'm a teapot. |
| 429 | Too Many Requests -- You're requesting too much data! Please slow down! |
| 500 | Internal Server Error -- We had a problem with our server. Please try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |