OpenWeather API - Weather Forecast, Air Quality, History

Pull current weather, 5 day and 8 day weather forecasts, weather alerts, historical weather back to 1979, air quality (AQI, PM2.5, PM10) and geocoding from the OpenWeather API (api.openweathermap.org) with your own API key, as one clean dataset row per observation, hour or day.

Works with the official OpenWeather APIs: Current Weather Data, 5 Day / 3 Hour Forecast, One Call API 3.0 (hourly forecast for 48 hours, daily forecast for 8 days, government weather alerts, timemachine history and daily aggregation), Air Pollution API (current, 4 day forecast and history) and Geocoding API (direct, zip and reverse). Give coordinates, city names or postcodes, and the actor returns deduplicated rows you can download as JSON, CSV or Excel, schedule, or feed into dashboards, logistics, energy and agriculture models, Google Sheets and AI agents. Bring your own API key.

BYOK, not live-tested: every endpoint, parameter and enum comes from the OpenWeather documentation on openweathermap.org, but the actor has not been run against a live OpenWeather key. Test calls with an invalid key confirmed the API host and the authentication answers, but the gateway checks the key before it routes, so the exact paths rest on the documentation.

What it does

• Current weather: temperature, feels like, min and max, humidity, pressure, wind speed, gust and direction, cloud cover, visibility, rain and snow over the last hour, sunrise and sunset, and the weather description, one row per location.
• 5 day forecast: 40 three hour steps per location with temperature, feels like, humidity, pressure, wind, cloud cover, probability of precipitation, rain and snow volume and the part of day.
• Hourly forecast (48 hours) and daily forecast (8 days) from One Call API 3.0, with dew point, UV index, morning, day, evening and night temperatures, moonrise, moonset and moon phase.
• Government weather alerts from national weather services, with sender, event, start and end time, description and tags.
• Historical weather: the weather at any timestamp from 1979-01-01 to 4 days ahead (timemachine), or daily aggregates (min, max, morning, afternoon, evening and night temperature, total precipitation, humidity, pressure, cloud cover and maximum wind) for any date from 1979-01-02 to 1.5 years ahead.
• Air quality: the Air Quality Index (1 Good to 5 Very Poor) and concentrations of CO, NO, NO2, O3, SO2, NH3, PM2.5 and PM10, now, as a 4 day hourly forecast, or hourly history since 27 November 2020.
• Geocoding: up to 5 places per city name, the centroid of a postcode, or the place names at a pair of coordinates, with local names in many languages.
• Any location: latitude and longitude, place names such as London,GB or Austin,TX,US, or postcodes such as zip:E14,GB, mixed freely in one run. Names are resolved through the Geocoding API, as OpenWeather recommends now that its built-in geocoder is deprecated.
• Units and languages: metric, imperial or standard units, and weather descriptions in about 50 documented languages.
• Pay only for results: refused and empty lookups are recorded as a free row that says why, never charged.

How to get an API key

Sign up for a free account at openweathermap.org, then copy your key from the API keys tab of your account. The free plan covers current weather, the 5 day forecast, air pollution and geocoding, with 60 calls a minute. One Call API 3.0 (the hourly and daily forecast, alerts and history modes) needs the separate "One Call by Call" subscription, which includes 1,000 free calls a day and then bills per call. A new key can take up to 2 hours to activate. Paste the key into the API key field, or set the DATA_API_KEY secret. The API requires the key as the appid query parameter, so it is sent only to api.openweathermap.org and is removed from everything the actor logs.

Input

Field	Modes	Description
mode	all	current (default), forecast, hourlyForecast, dailyForecast, alerts, historyHourly, historyDaily, airQuality, airQualityForecast, airQualityHistory or geocode
locations	all	One per line: 51.5074,-0.1278, London,GB, Austin,TX,US or zip:10001,US
units	weather modes	metric (default), imperial or standard
language	weather modes	A documented lang code such as en (default), de, fr, es, pt_br, zh_cn
forecastSteps	forecast	Number of 3 hour steps, 1 to 40 (default 40)
dateFrom, dateTo	historyDaily, airQualityHistory	Date range as YYYY-MM-DD, at most 366 days
timezoneOffset	historyDaily	Optional tz override in the +XX:XX form
times	historyHourly	ISO 8601 date-times, one per line, such as 2024-01-15T12:00:00Z
geocodeLimit	geocode	Places per name, 1 to 5 (default 5)
maxResults	all	Row ceiling for the run (default 100)
requestsPerMinute	all	Pacing, default 60 (the free plan limit)
apiKey	all	Your OpenWeather API key (or the DATA_API_KEY secret)

Example: a 5 day forecast for London and New York in metric units.

{
    "mode": "forecast",
    "locations": ["51.5074,-0.1278", "New York,NY,US"],
    "units": "metric"
}

Example: daily weather summaries for the first week of June 2024 in Austin.

{
    "mode": "historyDaily",
    "locations": ["Austin,TX,US"],
    "dateFrom": "2024-06-01",
    "dateTo": "2024-06-07",
    "units": "imperial"
}

Example output

An illustrative 5 day forecast row, shaped like the documented API response (values are an example, not real data). Every field the API returns is kept; only some are shown.

{
    "mode": "forecast",
    "modeLabel": "5 day forecast, 3 hour steps",
    "recordType": "forecast",
    "location": "51.5074,-0.1278",
    "locationType": "coordinates",
    "resolvedName": "London",
    "country": "GB",
    "state": null,
    "lat": 51.5074,
    "lon": -0.1278,
    "unitSystem": "metric",
    "found": true,
    "timeUtc": "2026-10-18T12:00:00.000Z",
    "timeLocal": "2026-10-18T13:00:00+01:00",
    "conditions": "light rain",
    "tempNow": 14.2,
    "tempHigh": 14.9,
    "tempLow": 13.8,
    "feelsLike": 13.6,
    "humidityPct": 78,
    "pressureHpa": 1012,
    "windSpeed": 5.1,
    "windDeg": 230,
    "windGust": 9.4,
    "cloudsPct": 90,
    "precipChancePct": 64,
    "precipMm": 0.42,
    "snowMm": null,
    "aqi": null,
    "pm2_5": null,
    "pm10": null,
    "dt": 1792324800,
    "main": { "temp": 14.2, "feels_like": 13.6, "temp_min": 13.8, "temp_max": 14.9, "pressure": 1012, "humidity": 78 },
    "weather": [{ "id": 500, "main": "Rain", "description": "light rain", "icon": "10d" }],
    "visibility": 10000,
    "pop": 0.64,
    "rain": { "3h": 0.42 },
    "sys": { "pod": "d" },
    "dt_txt": "2026-10-18 12:00:00",
    "retrievedAt": "2026-10-18T09:00:00.000Z",
    "note": null
}

FAQ

What is the OpenWeather API?

OpenWeather (OpenWeather Ltd, London) runs openweathermap.org, one of the most widely used weather APIs. Its REST APIs on api.openweathermap.org return current weather, forecasts, historical weather, air pollution and geocoding for any latitude and longitude on Earth, built on the proprietary OpenWeather Model, global weather models, satellites, radar and weather stations, authenticated with an appid API key.

Do I need my own OpenWeather API key?

Yes. This is a bring-your-own-key actor: it calls OpenWeather with your key, under your plan and terms. A missing, rejected or exhausted key ends the run cleanly with a status message that explains what to change, and nothing is charged.

Which modes work on the free OpenWeather plan?

Current weather, the 5 day / 3 hour forecast, all three air quality modes and geocoding. The hourly forecast, daily forecast, alerts, historical weather and daily summary modes call One Call API 3.0, which needs the separate One Call by Call subscription (1,000 free calls a day). A key without it gets a clear "not on your plan" message.

How far back does the weather history go?

One Call API 3.0 returns weather for any timestamp from 1 January 1979 up to 4 days ahead, and daily aggregates from 2 January 1979 up to 1.5 years ahead. Air pollution history starts on 27 November 2020.

Can I look up weather by city name or zip code?

Yes. A line such as London,GB or Austin,TX,US is resolved through the OpenWeather Geocoding API, and a postcode is written with zip: and its ISO 3166 country code, such as zip:10001,US or zip:E14,GB. Each name or postcode costs one extra Geocoding request. Coordinates skip that step.

What does the air quality index mean?

OpenWeather's AQI runs from 1 (Good) through 2 (Fair), 3 (Moderate) and 4 (Poor) to 5 (Very Poor), based on SO2, NO2, PM10, PM2.5, O3 and CO concentrations in micrograms per cubic metre. Every row also keeps the raw pollutant concentrations.

What do I pay?

Pay per result: 0.008 USD per current weather or current air quality row, 0.005 USD per forecast step, forecast hour or day, alert, historical time or day, or air quality hour, and 0.005 USD per geocoding match. Refused and empty lookups are never charged. Your OpenWeather plan is billed separately by OpenWeather, and each request counts against it.

What happens if my key is wrong or my call limit runs out?

A 401 (wrong key, a key that is not active yet, or One Call 3.0 without its subscription) or a 429 (the daily or monthly call limit is used up) ends the run cleanly with the API's own words. Server errors are retried. A location the API refuses (400) or has no data for (404) becomes a free row with the reason, and the run moves on.

Pricing

Event	Price	Charged for
current-conditions	0.008 USD	Each location's current weather or current air quality
forecast-or-history-period	0.005 USD	Each forecast step, hour or day, alert, historical time or day, or air quality hour
location-match	0.005 USD	Each place the Geocoding API returns

Keyword map

OpenWeather API, OpenWeatherMap API, weather API, weather forecast API, current weather API, 5 day weather forecast, hourly weather forecast, 8 day forecast, One Call API 3.0, historical weather data, weather history API, weather since 1979, air quality API, air pollution API, AQI, PM2.5, PM10, weather alerts API, geocoding API, weather by city, weather by zip code, weather by coordinates.

Terms and data use

OpenWeather's self-service plans, including the free plan, are licensed under the Open Database License (ODbL), with products under CC BY-SA 4.0 (OpenWeather terms and conditions of sale, clause G; the pricing page's Licence section). Commercial use is allowed and storing the data is allowed. Two conditions apply: visible attribution to OpenWeather wherever the data is shown (for example "Weather data provided by OpenWeather" with a link to openweathermap.org), and share-alike, meaning that if you build a reusable database from OpenWeather data and make it available outside your organisation, it must be offered under the ODbL too. Enterprise contracts replace these terms with negotiated ones. Run this actor with your own key, keep the attribution, and check your plan's terms before redistributing the results. This actor is not affiliated with or endorsed by OpenWeather.