# OpenWeather API - Weather Forecast, Air Quality, History (`nabeelbaghoor/openweather-weather-forecast-air-quality-api`) Actor Weather data from the OpenWeather API: current weather, 5 day 3 hour forecast, One Call 3.0 hourly and 8 day forecasts, alerts and history back to 1979, air quality (AQI, PM2.5) and geocoding, by coordinates, city or postcode. Bring your own key. - **URL**: https://apify.com/nabeelbaghoor/openweather-weather-forecast-air-quality-api.md - **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community) - **Categories:** Developer tools, Business, Integrations - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $8.00 / 1,000 current weather or air quality returneds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## 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. ```json { "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. ```json { "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. ```json { "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. # Actor input Schema ## `mode` (type: `string`): Current weather, the 5 day forecast, air quality and geocoding work on the free OpenWeather plan. The hourly and daily forecasts, alerts and both history modes call One Call API 3.0, which needs the separate One Call by Call subscription (1,000 free calls a day). ## `locations` (type: `array`): One location per line: latitude,longitude (51.5074,-0.1278), a place name as city, city,country or city,state,country with ISO 3166 codes (Paris,FR or Austin,TX,US), or a postcode with its country after zip: (zip:E14,GB or zip:10001,US). Names and postcodes are turned into coordinates through the OpenWeather Geocoding API, one extra request each. ## `units` (type: `string`): Unit system for temperature and wind speed. Precipitation is always in mm. Air quality and geocoding ignore units. ## `language` (type: `string`): Language of weather descriptions and place names, using the lang codes OpenWeather documents. ## `forecastSteps` (type: `integer`): 5 day forecast only: how many 3 hour steps to return per location (the cnt parameter). 40 covers 5 days, 8 covers 24 hours. ## `dateFrom` (type: `string`): Daily weather summary and air quality history only, as YYYY-MM-DD. Daily summaries go back to 1979-01-02 and up to 1.5 years ahead; air quality history starts on 2020-11-27. ## `dateTo` (type: `string`): Daily weather summary and air quality history only, as YYYY-MM-DD. Leave empty for a single day. At most 366 days per run; the daily summary makes one request per day per location. ## `timezoneOffset` (type: `string`): Daily weather summary only, optional: the tz parameter in the +XX:XX form (for example -05:00) when the location's time zone is detected wrongly. Leave empty to let OpenWeather detect it. ## `times` (type: `array`): Historical weather at given times only: one ISO 8601 date-time per line (2024-01-15T12:00:00Z), or a date (read as 12:00 UTC). Each time and location is one request, from 1979-01-01 up to 4 days ahead. ## `geocodeLimit` (type: `integer`): Geocoding only: the most places to return for each name or coordinate pair (the limit parameter, up to 5). ## `maxResults` (type: `integer`): The most rows this run returns and charges for. A 5 day forecast is 40 rows per location, an air quality forecast about 96. ## `requestsPerMinute` (type: `integer`): Pacing. The free plan allows 60 calls a minute; paid plans allow more. ## `apiKey` (type: `string`): Your own OpenWeather API key (the appid) from the API keys tab of your openweathermap.org account. Stored as a secret and sent only to api.openweathermap.org as the appid parameter the API requires; it is never logged. You can instead set the DATA_API_KEY environment secret. ## Actor input object example ```json { "mode": "current", "locations": [ "51.5074,-0.1278", "New York,NY,US" ], "units": "metric", "language": "en", "forecastSteps": 40, "geocodeLimit": 5, "maxResults": 100, "requestsPerMinute": 60 } ``` # Actor output Schema ## `records` (type: `string`): One row per observation, step, day, alert, air quality hour or place. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "locations": [ "51.5074,-0.1278", "New York,NY,US" ] }; // Run the Actor and wait for it to finish const run = await client.actor("nabeelbaghoor/openweather-weather-forecast-air-quality-api").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "locations": [ "51.5074,-0.1278", "New York,NY,US", ] } # Run the Actor and wait for it to finish run = client.actor("nabeelbaghoor/openweather-weather-forecast-air-quality-api").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "locations": [ "51.5074,-0.1278", "New York,NY,US" ] }' | apify call nabeelbaghoor/openweather-weather-forecast-air-quality-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/openweather-weather-forecast-air-quality-api" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/YNVyFyd5CeIGEcFVf/builds/kaYErvnyf0Sauq6TX/openapi.json