Weather Forecast API

Weather Forecast API is a weather forecast api that resolves one place into daily forecast or historical weather rows with hourly detail and best-effort air quality. Each Dataset item follows a documented 54-field contract and keeps the resolved coordinates, timezone, units, source values, and processing provenance together.

• Forecast and history in one contract — select 1–16 forecast days or a paired historical date range without changing the output shape.
• Daily and hourly weather together — use daily temperature, wind, precipitation, sunlight, and nested hourly values in the same row.
• Resolved place context — retain the matched location, country, region, city, coordinates, and timezone for reproducible downstream joins.
• Explicit air-quality coverage — receive current and hourly air-quality objects when available plus a plain-language note when coverage differs.

The smallest useful run is one forecast day: one $0.01 Actor Start plus one $0.002 Result costs $0.012 when one row is written.

Why Choose Weather Forecast API

One place becomes analysis-ready records. Submit a country, region, city, town, or district query and receive one resolved match with coordinates and daily rows, avoiding a separate geocoding join in ordinary workflows.

Forecast and historical modes share 54 fields. A scheduled forecast and a bounded historical pull can feed the same table, database model, or automation because identifiers, units, weather measures, nested objects, and provenance remain consistently named.

Daily decisions retain hourly evidence. Top-level values summarize each day, while hourly_forecast preserves the time-grained temperatures, weather labels, wind, precipitation, and related source values needed to explain a daily alert.

Missing values stay distinguishable. The Actor does not turn unavailable source values into invented zeroes. Air-quality gaps carry air_quality_note, and current-condition fields appear only where the source observation belongs.

Row counts are known before the run works. Forecast mode accepts 1–16 days. A historical range has no length limit, and because both endpoints are inclusive the exact row count follows from the dates — the run states it in its first status line, before any charge.

Weather variables follow the official Open-Meteo forecast documentation, while historical mode uses its documented Historical Weather API. These sources describe modeled weather data; they are not official local warnings or station certifications.

Quick Start Guide

1. Configure the location and window

Open the Input tab. A working Tokyo, Japan example is prefilled with three forecast days. Keep that input, change days from 1 to 16, or provide both start_date and end_date to request history.

2. Run the Actor

Select Start. The Actor validates the window, resolves one place, retrieves weather and best-effort air quality, and writes one Dataset item for each returned day.

3. Collect the daily rows

Open the default Dataset to preview results or export JSON, CSV, Excel, XML, or RSS. In an automated flow, preserve defaultDatasetId from the run object and read items from that Dataset after the run reaches a terminal state.

Input Parameters

Weather Forecast API requires one location; forecast length and a paired historical range are optional controls, and dates take precedence over days when both dates are supplied.

Parameter	Type	Required	Description	Example
location	string	Yes	Non-empty country, region, city, town, or district query resolved to one place. Add regional context when a name is ambiguous.	Tokyo, Japan
days	integer	No	Forecast length from 1 to 16. Runtime uses 3 when omitted and ignores it in historical mode.	1
start_date	string	No	Range start in YYYY-MM-DD or a past-relative form such as 30 days; requires end_date.	2026-07-01
end_date	string	No	Range end using the same syntax; it cannot precede the start. No maximum length.	2026-07-07

The shared Tokyo forecast scenario used throughout these examples is:

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

Historical relative values accept singular or plural day, week, month, and year units. A relative month means 30 days and a relative year means 365 days. Both resolved dates are inclusive: equal endpoints request one day, endpoints 366 days apart return 367 rows, and a thirty-year range returns 10,958.

Window	Mode	Maximum returned rows
days: 1	forecast	1
days: 16	forecast	16
Same start and end date	historical	1
End 366 days after start	historical	367
start_date: 30 years	historical	10,958

Output Data Schema

Each Dataset row represents one returned calendar day and contains 54 top-level fields; nested hourly arrays are abbreviated below, while a real run keeps every source row returned for that day.

Group	Fields	What they provide
Request and place	status, mode, start_date, end_date, location, country, region, city, latitude, longitude, timezone	Resolution and window context for joins and diagnostics
Units and daily identity	temperature_unit, wind_speed_unit, date, weather	Units and the represented calendar day
Temperature and wind	temperature_max, temperature_min, temperature_mean, apparent_temperature_max, apparent_temperature_min, wind_speed_max, wind_gusts_max, wind_direction_dominant, wind_direction_label	Daily ranges and dominant wind conditions
Water and sunlight	precipitation_sum, precipitation_probability_max, rain_sum, snowfall_sum, precipitation_hours, uv_index_max, sunrise, sunset, daylight_hours, sunshine_hours	Daily precipitation and solar measures
Current conditions	current_temperature, current_apparent_temperature, current_humidity, current_weather, current_cloud_cover, current_pressure, current_visibility_km, current_uv_index, current_wind_speed, current_wind_direction, current_wind_direction_label, current_wind_gusts, current_is_day, current_precipitation	Present observation fields on the matching forecast date
Nested and provenance	air_quality_note, hourly_forecast, air_quality_current, air_quality_hourly, processor, processed_at	Time-grained objects, coverage explanation, and processing stamps

Abbreviated example — the arrays are truncated here; a real one-day run returns all hourly values supplied for that day and still exposes the full 54-field top-level contract:

{
  "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-08-13",
  "weather": "Mainly clear",
  "temperature_max": 33.1,
  "temperature_min": 26.4,
  "precipitation_probability_max": 20,
  "hourly_forecast": [
    {"time": "2026-08-13T12:00", "temperature": 31.8}
  ],
  "air_quality_current": {"european_aqi": 24},
  "air_quality_hourly": [
    {"time": "2026-08-13T12:00", "european_aqi": 24}
  ],
  "processor": "https://apify.com/agentx/weather-forecast-api",
  "processed_at": "2026-08-13T19:00:00+00:00"
}

Unavailable source values remain null or empty instead of becoming artificial measurements. Export the same Dataset as JSON for applications, CSV or Excel for analysis, or XML and RSS for compatible workflows.

Integration Examples

Weather Forecast API uses Actor ID Yn1ksjorQhCtBcLN6 with the same Tokyo one-day JSON input across REST, official clients, automation platforms, and MCP.

Actor ID

Yn1ksjorQhCtBcLN6

The name form agentx/weather-forecast-api is also supported where an Apify interface accepts Actor names.

HTTP

curl -X POST "https://api.apify.com/v2/acts/Yn1ksjorQhCtBcLN6/runs?waitForFinish=120" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"location":"Tokyo, Japan","days":1}'

Read results through the returned defaultDatasetId rather than assuming a successful process always wrote rows.

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("Yn1ksjorQhCtBcLN6").call(
    run_input={"location": "Tokyo, Japan", "days": 1}
)
items = list(client.dataset(run["defaultDatasetId"]).iterate_items())

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('Yn1ksjorQhCtBcLN6').call({
  location: 'Tokyo, Japan',
  days: 1,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();

Make.com

Add an Apify Run an Actor module, enter Yn1ksjorQhCtBcLN6, paste {"location":"Tokyo, Japan","days":1}, and map defaultDatasetId into a Get Dataset Items module.

n8n

Use an Apify node or authenticated HTTP Request node to start Yn1ksjorQhCtBcLN6 with the Tokyo JSON, wait for a terminal run status, then request items from the run's defaultDatasetId.

MCP

Connect the Apify MCP server, select agentx/weather-forecast-api, send location: Tokyo, Japan and days: 1, then ask the client to return the default Dataset items. The public schema lets an MCP client discover the same four input fields before calling the Actor.

Pricing

Weather Forecast API costs $0.002 per Result on the Free plan and less on paid plans, plus one $0.01 Actor Start per run; the smallest one-day run totals $0.012 when one row is written.

Billed event	Price	When charged
Actor Start	$0.01	Once when a run starts, including a run that later writes zero rows
Result	$0.002	Once per daily Dataset row written; $0.0018 on Bronze, $0.0016 on Silver, $0.0015 on Gold and above

The 256 MB runtime memory is included in the Actor's configured run shape; pricing follows the two billed events above. A one-day forecast is $0.01 + 1 × $0.002 = $0.012. A typical seven-day forecast that writes seven rows is $0.01 + 7 × $0.002 = $0.024. A full year of history writes 366 rows for $0.01 + 366 × $0.002 = $0.742. One seven-day run is cheaper than seven one-day runs because it pays Actor Start once rather than seven times.

Rows actually written determine Result charges. Failed place resolution or upstream retrieval can still incur Actor Start and return no items. Prices can change; verify the current Pricing page before budgeting a production schedule.

Use Cases

Operations forecast alerts. Schedule one place per run and evaluate precipitation_probability_max, snowfall_sum, wind_gusts_max, or current_visibility_km before dispatching field teams.

Event and venue planning. Combine date, weather, temperature_max, rain_sum, sunrise, and sunset for outdoor staffing, equipment, and timing decisions.

Historical demand analysis. Request a bounded date range and join temperature_mean, precipitation_sum, sunshine_hours, latitude, longitude, and timezone to sales, energy, or attendance records.

Air-quality context. Store air_quality_current, air_quality_hourly, and air_quality_note beside weather records while treating unavailable coverage explicitly rather than filling it with zero.

Application data feeds. Normalize the daily scalar fields into a database and retain hourly_forecast as JSON for drill-down views, rules, or model features.

Multi-location monitoring. Create one run per unambiguous place, keep the resolved coordinates, and merge results downstream using your own location identifier and run schedule.

Alternatives

Manual lookup is enough for an occasional human check when no structured history, automation, cost cap, or export is needed. It stops scaling when a workflow must preserve coordinates, hourly arrays, repeated snapshots, and consistent columns.

Open-Meteo's own APIs are the closest source-level alternative. They are preferable when you want to own geocoding, request composition, response joins, scheduling, storage, retries, and schema normalization directly; its Air Quality API documentation also explains the source variables used here.

General data-integration platforms may be preferable when weather is only one connector inside a larger managed stack. Business-intelligence suites may be preferable when your main need is dashboarding data you already possess rather than collecting it.

Choose something else if you need official emergency warnings, aviation-grade or station-certified observations, multiple locations in one Actor input, a guaranteed upstream service level, or safety-critical professional advice.

Limits and Troubleshooting

• No Dataset rows → the place may not resolve or an upstream request may fail → add country or region context, confirm the returned run logs, and retry with a distinctive location.
• One date is rejected → historical mode requires a pair → supply both start_date and end_date, or remove both and use days.
• Date range is rejected → the end precedes the start → submit valid absolute or past-relative values in order; the range itself has no maximum length.
• Current fields are null on future days → current conditions belong to the observation date → use the daily and hourly forecast fields for later dates.
• Air quality is empty for part of the window → source coverage can differ from weather coverage → inspect air_quality_note and treat air_quality_current or air_quality_hourly as optional.
• Fewer days arrive than requested → source availability controls returned dates → compare date, requested mode, Dataset count, and run logs before retrying.
• A run costs $0.01 but returns zero rows → Actor Start is billed before retrieval completes → validate location text and upstream availability; Result is billed only for rows written.
• A place resolves incorrectly → one geocoding match is selected → include the city, region, and country and verify latitude, longitude, and timezone before using the data.

For a reproducible defect, open an Issue with the run ID, UTC timestamp, exact input with secrets removed, resolved location if present, Dataset count, and the smallest relevant log excerpt.

Trust and Reliability

Runs use Apify's managed Actor infrastructure and expose terminal status, logs, Dataset storage, schedules, webhooks, API access, and charge limits through the platform. Billing is transparent at one start event and one event for each daily row written.

The Dataset contract documents 54 top-level fields, including request mode, resolved place, units, daily summaries, current conditions, nested hourly weather, nested air quality, and processing stamps. Source values remain null or empty when unavailable rather than being silently converted to fabricated measurements.

The Actor is designed for reproducible data workflows, not for official warnings. Monitor scheduled runs, validate critical thresholds against an appropriate authority, and keep a fallback for upstream outages when the workflow is operationally important.

Legal and Compliance

Data scope. Weather and air-quality records describe places and modeled environmental conditions. Follow the providers' current licenses, attribution requirements, and usage policies, including the public Nominatim usage policy.

Privacy. The Actor does not require personal data, but your surrounding workflow can combine location data with confidential or personal records. Apply appropriate access controls, retention limits, and purpose restrictions to those downstream datasets.

Terms and decisions. Use the Actor under Apify's terms and applicable law. Do not represent modeled output as an official warning, medical conclusion, insurance determination, or other regulated professional advice. This documentation is not legal advice.

Frequently Asked Questions

What does this weather forecast api return?

It returns one 54-field Dataset item per source day, including resolved location data, daily weather, current-condition values where applicable, nested hourly weather, best-effort air quality, and processing provenance.

Can this historical weather data api use relative dates?

Yes. Both endpoints accept past-relative day, week, month, or year values, as well as YYYY-MM-DD; month means 30 days, year means 365 days, and both dates must be supplied together.

Is this an hourly weather forecast api by city?

Yes, for one resolved city or other place per run. Each daily row includes hourly_forecast; add country or region context to reduce ambiguous place matches.

Is there a free weather API?

Open-Meteo provides an official source API with its own current terms, while this Actor is pay per event at $0.01 per start and $0.002 per daily result. Use the source directly when you prefer to own integration and storage.

Can I schedule runs to monitor weather over time?

Yes. Apify schedules can run the Actor repeatedly; store each run's processed_at, resolved coordinates, mode, and Dataset items so snapshots remain distinguishable.

Why are current-condition fields missing from future forecast rows?

Because those fields represent one current observation. They appear on the matching observation date, while future rows use daily summaries and hourly_forecast.

How many forecast or historical rows can one run return?

Forecast mode accepts 1–16 days. A historical range has no maximum length: both endpoints are inclusive, so 366 days apart returns 367 daily rows and thirty years returns 10,958.

Does the Actor guarantee air-quality values?

No. Air quality is best effort and its temporal coverage can differ from weather coverage; inspect air_quality_note and allow the nested air-quality fields to be empty.

Related AgentX Actors

AgentX publishes 77 Actors organized by category below; the three closest options add place, property, or business context to weather records.

Closest to this Actor:

• Google Maps Store Scraper — add public business and place records for the same target area.
• Realtor Property Scraper — connect environmental windows with residential listing research.
• Zillow Property Scraper — add a second property-market dataset for location analysis.

Business and Market Intelligence

• Google Keyword Trends — Google Trends keyword interest, compared five at a time
• Google Trends Scraper — Google Trends trending searches
• Google Maps Store Scraper — Google Maps business listings
• LinkedIn Company Lookup — LinkedIn company records
• LinkedIn Profile Lookup — LinkedIn profile records

Jobs and Hiring

• All Jobs Scraper — multi-platform job listings
• Bayt Jobs Scraper — Bayt job listings
• Glassdoor Jobs Scraper — Glassdoor job listings
• Indeed Jobs Scraper — Indeed job listings
• JobStreet Company Profile — JobStreet employer records
• Jooble Jobs Scraper — Jooble job listings
• LinkedIn Jobs Scraper — LinkedIn job listings
• Naukri Jobs Scraper — Naukri job listings
• Talent Jobs Scraper — Talent.com job listings
• ZipRecruiter Jobs Scraper — ZipRecruiter job listings

Social Media

• Instagram Creator Scraper — Instagram creator profiles
• Instagram Reels Scraper — Instagram Reels metadata
• Instagram Trending Scraper — Instagram trending content
• Medium Scraper — Medium articles
• Medium Profile Scraper — Medium author profiles
• Reddit Profile Scraper — Reddit user profiles
• Reddit Viral Scraper — Reddit viral posts
• SubReddit Info Scraper — subreddit metadata
• Subreddit Members Scraper — subreddit member lists
• Subreddit Posts Scraper — subreddit post feeds
• Telegram Chat Scraper — Telegram chat messages
• Telegram Info Scraper — Telegram channel metadata
• Telegram Member Adder — Telegram group membership management
• Telegram Member Scraper — Telegram group members
• Telegram Private Group Scraper — private Telegram group data
• TikTok Creator API — TikTok creator profiles
• TikTok User Lookup — TikTok account records
• X Twitter Community API — X community data
• X Twitter Profile Lookup — X profile records
• YouTube Creator Email Scraper — YouTube creator contact data

Video, Transcripts and Downloads

• All Video Scraper — multi-platform video metadata
• Video Transcript — multi-platform transcripts
• Video Captions Downloader — caption files
• Video to Social Post — video repurposed into social copy
• YouTube Transcript — YouTube transcripts
• TikTok Transcript — TikTok transcripts
• X Twitter Transcript — X video transcripts
• Facebook Transcript — Facebook video transcripts
• Bilibili Transcript — Bilibili transcripts
• Dailymotion Transcript — Dailymotion transcripts
• Rutube Transcript — Rutube transcripts
• Loom Transcript — Loom transcripts
• Wistia Transcript — Wistia transcripts
• Instagram Reels Downloader — Reels downloads
• Kick Clip Downloader — Kick clip downloads
• Linkedin Video Downloader — LinkedIn video downloads
• Pinterest Video Downloader — Pinterest video downloads
• Reddit Video Downloader — Reddit video downloads
• Snapchat Video Downloader — Snapchat video downloads
• TED Talk Downloader — TED talk downloads
• TikTok Live Downloader — TikTok live downloads
• Twitch VOD Downloader — Twitch VOD downloads
• Zoom Recording Downloader — Zoom recording downloads

E-Commerce and Retail

• All Shopping Scraper — multi-platform product data
• AliExpress Product Scraper — AliExpress products
• Amazon Storefront Scraper — Amazon Brand Store pages
• Bol Product Scraper — Bol.com products
• eBay Seller Leads API — eBay seller records
• Hepsiburada Product Scraper — Hepsiburada products
• Kakaku Product Scraper — Kakaku.com products
• Rakuten Product Scraper — Rakuten products

Classifieds and Automotive

• All Vehicle Scraper — multi-platform vehicle listings
• AutoTrader Vehicle Search — AutoTrader US listings
• AutoTrader UK Vehicle Search — AutoTrader UK listings

Real Estate

• All Property Scraper — multi-platform property listings
• Homes Property Scraper — Homes.com listings
• MagicBricks Property Scraper — MagicBricks listings
• NoBroker Property Scraper — NoBroker listings
• Property24 Property Scraper — Property24 listings
• Realtor Property Scraper — Realtor.com listings
• Zillow Property Scraper — Zillow listings

Support and Community

Ask about forecast windows, historical dates, place resolution, hourly weather, or air-quality coverage in the AgentX community on Telegram; for a reproducible bug, open an Issue with the run ID and the exact input.

AgentX is an Arcyton brand — arcyton.com.

Last Updated: August 13, 2026