Weather Forecast API

Weather Forecast API turns one human-readable place query into structured daily weather records, nested hourly observations, and best-effort air-quality data. It supports short forecasts and bounded historical date ranges without making you assemble geocoding, forecast, archive, and air-quality requests yourself.

• Resolve one country, region, city, town, or district query to a single geographic match.
• Request a 1–16 day forecast, or provide paired absolute or past-relative dates.
• Receive one 58-field Dataset row per day with nested hourly weather and air-quality objects.
• Use the Apify Console, REST API, client libraries, schedules, webhooks, or MCP-compatible workflows.

Why Choose This API

Weather Forecast API is designed for workflows that need records rather than a visual forecast page. A run geocodes one location, selects forecast or date-range mode, requests weather data, joins the available air-quality response, and writes daily JSON items to the default Dataset. That predictable one-row-per-day shape works well for spreadsheets, databases, monitoring jobs, and model features.

The Actor exposes the behavior that matters for planning. Forecast mode accepts 1 through 16 days. Date-range mode requires both endpoints and limits the difference between them to 366 days, so an inclusive response can contain as many as 367 daily rows. Temperature is returned in Celsius and wind speed in kilometres per hour. Location lookup returns one match, so a distinctive query such as Tokyo, Japan is safer than an ambiguous city name.

Weather values come from Open-Meteo. Its forecast documentation explains the model-backed forecast variables and the maximum forecast horizon, while its historical weather documentation describes archive data. Air quality uses the separate Open-Meteo Air Quality API. Place resolution uses Nominatim; users running repeated location jobs should understand the public service's usage policy.

This Actor does not promise station-grade measurements, uninterrupted upstream availability, or a perfect place match. Weather models differ by region and update schedule. Air-quality coverage can be shorter than the requested weather period, and historical air quality is best-effort. The Dataset records the returned status and air-quality note so downstream code can distinguish available data from gaps.

Quick Start Guide

Open the Actor in the Apify Console, enter a location, choose either forecast days or a paired date range, and select Start. The smallest forecast input is:

{
  "location": "Tokyo, Japan",
  "days": 3
}

If days is omitted, runtime uses 3. Do not send only one date: start_date and end_date must be supplied together. When both dates are present, days is ignored. After the run finishes, open the default Dataset to inspect, download, or query the daily rows.

For automation, call Actor ID Yn1ksjorQhCtBcLN6 or the name agentx/weather-forecast-api. Preserve the run's defaultDatasetId; it is the stable pointer used by Apify clients and REST endpoints to retrieve results. A successful process can still contain zero rows if the place cannot be resolved or an upstream weather response is unavailable, so always inspect both run status and Dataset item count.

Billing is event based. The Actor Start event is charged when execution begins, including a run that later produces no weather rows. The Result event is charged once for every daily row written. Set an Apify maximum total charge when your calling surface supports it, especially for date ranges.

Input Parameters

location is the only required field. It must contain non-whitespace text naming a country, region, city, town, or district. Runtime sends the query to Nominatim and uses exactly one returned match. The response contributes the resolved display name, country, region, city-like value, latitude, and longitude. Geocoding is not a fuzzy business-directory search; spelling, language, and ambiguity can change the result. Add country or regional context when precision matters.

days is an optional integer from 1 to 16. It controls forecast length only when dates are absent. Runtime defaults to 3 rather than requiring the public input to carry a hidden value. Forecast data can include current conditions, but those current fields belong only to the daily row matching the observation date. Later forecast rows retain daily and hourly values while their current-condition fields are null.

start_date and end_date switch the Actor to date-range mode. Each accepts an ISO date in YYYY-MM-DD format or one past-relative value: N day, N days, N week, N weeks, N month, N months, N year, or N years. Relative values subtract from the Actor's local date.today(). A month is interpreted as 30 days and a year as 365 days; this is arithmetic shorthand, not calendar-month logic.

Both resolved dates must be present, the end must be on or after the start, and their difference must not exceed 366 days. Because endpoints are inclusive, a zero-day difference requests one day and a 366-day difference may return 367 rows. Upstream archive availability still determines whether every requested day is present.

Output Data Schema

The default Dataset contains one item per returned calendar day. Each row has 58 top-level fields covering processing metadata, resolved location, units, daily weather, current conditions, air-quality status, and three nested data containers. The schema view orders the columns for review, while downloads can include the complete nested objects.

Important groups include temperature_max, temperature_min, temperature_mean, apparent-temperature extremes, wind speed and gust maxima, dominant wind direction, precipitation and snowfall totals, precipitation probability, UV index, sunrise, sunset, daylight hours, and sunshine hours. hourly_forecast contains the expanded hourly weather rows for that date.

Current fields such as current_temperature, current_humidity, current_pressure, current_visibility_km, and current_wind_speed describe a present observation, not a daily summary. In forecast mode they appear only on the row matching the current observation date. Do not treat null current values on future days as missing daily forecasts.

Air quality is deliberately explicit. air_quality_status and air_quality_note describe the coverage. Forecast air quality is requested for no more than seven days even when weather covers up to sixteen. air_quality_current holds current AQI, particulate, gas, pollen, UV, or haze indicators when supplied. air_quality_hourly holds rows assigned to that day. Historical air quality failure does not necessarily fail the weather run.

A shortened representative row looks like this:

{
  "status": "success",
  "mode": "forecast",
  "location": "Tokyo, Japan",
  "country": "Japan",
  "latitude": 35.6762,
  "longitude": 139.6503,
  "timezone": "Asia/Tokyo",
  "temperature_unit": "celsius",
  "wind_speed_unit": "kmh",
  "date": "2026-07-24",
  "weather": "Partly cloudy",
  "temperature_max": 33.1,
  "temperature_min": 26.4,
  "hourly_forecast": [],
  "air_quality_status": "forecast",
  "air_quality_current": {},
  "air_quality_hourly": []
}

Field presence and values depend on the upstream response. Consumers should tolerate nulls, unknown additional keys inside nested hourly objects, and empty air-quality arrays.

Integration Examples

With the Apify REST API, POST the run input to the Actor endpoint, wait for completion, then GET items from the returned default Dataset. Put the token in the Authorization header or the official client's token option; never commit it to source control. The request body is the same JSON used in the Console.

For a bounded historical request, use:

{
  "location": "Munich, Germany",
  "start_date": "2026-06-01",
  "end_date": "2026-06-07"
}

In Python, create ApifyClient, call client.actor("Yn1ksjorQhCtBcLN6").call(run_input=run_input), and iterate client.dataset(run["defaultDatasetId"]).iterate_items(). In JavaScript, call client.actor("agentx/weather-forecast-api").call(input) and then list items from run.defaultDatasetId.

Schedules are useful for a daily forecast snapshot. Webhooks can notify another system after a terminal run. MCP-capable clients can discover the public input schema, call the Actor, poll the run, and read Dataset items. Whichever interface you use, validate the exact build when testing a release, and check the Dataset rather than treating a SUCCEEDED run alone as proof that weather rows exist.

Pricing & Cost Calculator

Current pay-per-event pricing is $0.02 for Actor Start and $0.01 for each Result row. A three-day forecast that returns three rows costs approximately $0.05: one $0.02 start plus three $0.01 results. A sixteen-day forecast costs approximately $0.18 when all sixteen rows are written. A seven-day date range costs approximately $0.09.

Inclusive dates are the common source of calculation mistakes. 2026-06-01 through 2026-06-07 contains seven rows, not six. The maximum endpoint difference of 366 days can contain 367 results and cost about $3.69 including start. These examples exclude any platform-level compute, storage, transfer, or plan charges that Apify may show separately.

The start charge applies even when a location has no match, upstream retrieval fails, or no Dataset rows are written. Result charges follow actual daily writes, not the requested days value. Estimate with 0.02 + 0.01 × expected daily rows, then use a charge cap where available. Prices can change, so the Actor's current Pricing tab remains authoritative.

Use Cases & Applications

Operations teams can schedule forecasts for depots, project sites, venues, or service regions and route the rows into alerting rules. Temperature, precipitation probability, snowfall, wind gusts, and visibility help create operational thresholds, though decisions that affect safety should use appropriate professional sources and local warnings.

Analysts can assemble bounded historical samples for demand studies, retail planning, energy exploration, or event analysis. The resolved coordinates and timezone make joins more reproducible than raw place text alone. Researchers should record run time, upstream provenance, and model limitations because re-running a forecast later may not reproduce the earlier model output.

Developers can normalize daily weather into an application database while retaining hourly_forecast as JSON. Air-quality status fields make it possible to create separate completeness rules rather than silently filling missing pollution values. Multi-location workflows should use one run per place and respect upstream service policies instead of trying to pass multiple locations into the single location field.

FAQ

Does it support worldwide locations?

It accepts free-text places and uses Nominatim to resolve one match. Coverage is broad, but a query may be ambiguous, unmatched, or resolved to a different place than intended. Include country and region context and verify the returned coordinates.

Can I request only one historical endpoint?

No. Both start_date and end_date are required for date-range mode. If neither is present, the Actor uses forecast mode and applies days.

Why are current fields null on future rows?

They represent one present observation. Runtime attaches them only to the daily row whose date matches that observation. Daily and hourly forecast values remain available on later rows.

Why is air quality missing before weather ends?

Forecast air quality is limited to seven days while weather can extend to sixteen. Historical air-quality retrieval is best-effort and can be unavailable without invalidating weather results. Read air_quality_status and air_quality_note.

Does a successful run always contain data?

No. A handled geocoding or upstream failure can finish without rows. Check Dataset item count and relevant logs. The start event may still have been charged.

Are relative months calendar months?

No. Runtime treats one month as 30 days and one year as 365 days, subtracted from the Actor's local date.

Trust & Certifications

The Actor publishes its current input and Dataset contracts, returns source-resolution metadata, and exposes coverage notes instead of representing unavailable air quality as complete. Release verification should combine JSON-schema validation, static checks, a cloud build, an exact-build run, and independent Dataset and key-value-store readback.

No claim is made that this Actor, Open-Meteo, Nominatim, or the returned values are certified for aviation, emergency response, medical advice, insurance, or other regulated safety decisions. Forecasts are model outputs and can change. Historical values can reflect gridded model or reanalysis data rather than a physical station at the resolved coordinates.

Users should monitor their own scheduled runs, validate critical thresholds, and keep fallbacks for upstream outages. The Actor does not use Apify proxy rotation for its direct weather and geocoding calls, and it cannot guarantee an upstream service-level agreement.

Legal & Compliance

Use the Actor and returned data in accordance with applicable law, Apify terms, and the source providers' licenses and policies. Open-Meteo documents its sources and usage options on its official pages. Nominatim's public endpoint has a specific usage policy, including rate and identification expectations; high-volume or recurring deployments may require an alternative provider or self-hosted service.

Weather and air-quality records ordinarily describe places rather than people, but a user's surrounding workflow can still combine them with personal or confidential information. Apply suitable access controls, retention rules, and purpose limitations to your own datasets. Do not present modeled output as an official warning or professional determination.

Attribution, licensing, commercial-use rights, and provider terms can evolve. Review the current official pages for the usage pattern and volume you operate. This README describes Actor behavior and is not legal advice.

Related Tools

Google Maps Store Scraper can add place and business context around a target area. Realtor Property Scraper and Zillow Property Scraper can provide property records for location-based analysis.

LinkedIn Company Lookup can enrich organization workflows, Twitter Info Scraper adds public account metadata, and YouTube Market Intelligence supports channel-market research. Each related Actor has its own inputs, billing, coverage, and limitations; they are not automatically invoked by Weather Forecast API.

Support & Community

For usage questions, reproducible failures, or schema issues, contact AgentX support on Telegram. Include the Actor name, run ID, UTC timestamp, input with secrets removed, expected behavior, actual Dataset item count, and the smallest relevant log excerpt. Do not send Apify tokens or other credentials.

Use the Actor's Apify page for the current input schema, pricing, builds, and run history. Before reporting missing data, verify the resolved location, coordinates, mode, dates, air_quality_status, and Dataset count. Upstream model or geocoding issues are easier to diagnose when the exact place and date window are included.

Last updated: July 23, 2026.