Geocoded Weather Extractor (Actor/Fetcher)

A simple, fast, and privacy‑aware weather data fetcher you can run as an Actor or locally.
Give it a location and choose hourly, daily, or weekly (aggregated) output.
Designed for business use: clean outputs, predictable schemas, and vendor‑neutral messaging.

---

✨ Features

• Three granularities: hourly, daily, or weekly (derived from daily via ISO‑week aggregation).
• Pick your variables: choose exactly which fields you want included.
• Timezone‑aware: set a specific IANA timezone or use automatic inference.
• Structured outputs: overview JSON + normalized rows in the Dataset.
• Drop‑in for analytics: consistent schemas for easy ingestion to BI tools or warehouses.
• Production‑ready: typed code, input schema validation, and clear logging.

---

🧠 How it works (high level)

1. The actor resolves the provided free‑text location to coordinates.
2. It fetches a forecast for the requested variables and timeframe.
3. It writes:
   • An OUTPUT JSON summarizing the run (resolved location, coordinates, timezone, variables, etc.).
   • A Dataset with one row per timestamp (hour/day) or per ISO week when using weekly mode.

---

📥 Input

The actor accepts the following JSON input (also defined in .actor/input_schema.json).

{
  "location": "Prague, CZ",
  "mode": "hourly",
  "hourly": ["temperature_2m", "precipitation"],
  "daily": ["temperature_2m_max", "temperature_2m_min", "precipitation_sum"],
  "timezone": "auto",
  "forecastDays": 3
}

Fields

Field	Type	Required	Description
location	string	✅	Free‑text place (e.g., "Prague" or "Prague, CZ").
mode	"hourly" | "daily" | "weekly"		Data granularity; weekly aggregates daily values by ISO week. Default: "hourly".
hourly	string[]		Hourly variables to include when mode = "hourly".
daily	string[]		Daily variables to include when mode = "daily" or "weekly".
timezone	string		"auto" to infer from coordinates, or any IANA name (e.g., "Europe/Prague").
forecastDays	integer (1–7)		Number of days to fetch.

Tip: You can safely omit hourly or daily if they are not relevant to your chosen mode.

---

📤 Outputs

Key‑value store (OUTPUT)

{
  "input_location": "Prague, CZ",
  "resolved_name": "Prague, Hlavni mesto Praha, Czechia",
  "latitude": 50.08,
  "longitude": 14.43,
  "timezone": "Europe/Prague",
  "timezone_abbreviation": "CEST",
  "elevation": 194,
  "mode": "hourly",
  "variables": ["temperature_2m", "precipitation"],
  "fetched_at": "2025-09-21T10:11:12.345Z"
}

Dataset

• Hourly mode: one item per time (ISO datetime).
• Daily mode: one item per date (ISO date).
• Weekly mode: one item per iso_week (e.g., 2025-W38) with start_date, end_date, and aggregated metrics.

Example (hourly row):

{
  "mode": "hourly",
  "time": "2025-09-21T12:00:00Z",
  "input_location": "Prague, CZ",
  "resolved_name": "Prague, Hlavni mesto Praha, Czechia",
  "latitude": 50.08,
  "longitude": 14.43,
  "temperature_2m": 23.1,
  "precipitation": 0.0
}

Example (weekly row):

{
  "mode": "weekly",
  "iso_week": "2025-W38",
  "input_location": "Prague, CZ",
  "resolved_name": "Prague, Hlavni mesto Praha, Czechia",
  "latitude": 50.08,
  "longitude": 14.43,
  "start_date": "2025-09-15",
  "end_date": "2025-09-21",
  "days_in_week": 7,
  "temperature_2m_max": 26.4,
  "temperature_2m_min": 12.2,
  "precipitation_sum": 4.6
}

---

🧮 Weekly aggregation rules

When mode = "weekly", the actor aggregates daily series by ISO week:

• Variables ending in _sum (and precipitation_sum): sum
• Variables ending in _max: max
• Variables ending in _min: min
• All other numeric series: average

Non‑numeric or missing values are ignored in the aggregation. Weeks are labeled using ISO format (YYYY-Www).

---

🧩 Example inputs

Hourly forecast (2 variables, 24 hours default window depending on source):

{
  "location": "Berlin, DE",
  "mode": "hourly",
  "hourly": ["temperature_2m", "precipitation"],
  "timezone": "Europe/Berlin",
  "forecastDays": 1
}

Daily forecast (5 days):

{
  "location": "Lisbon, PT",
  "mode": "daily",
  "daily": ["temperature_2m_max", "temperature_2m_min", "precipitation_sum"],
  "timezone": "auto",
  "forecastDays": 5
}

Weekly aggregates from daily:

{
  "location": "Prague, CZ",
  "mode": "weekly",
  "daily": ["temperature_2m_max", "temperature_2m_min", "precipitation_sum"],
  "timezone": "Europe/Prague",
  "forecastDays": 7
}

---

🏷️ Data dictionary (selected variables)

• temperature_2m — Near‑surface air temperature (°C).
• precipitation / precipitation_sum — Precipitation amount (mm).
• relative_humidity_2m — Relative humidity (%).
• apparent_temperature — Feels‑like temperature (°C).
• pressure_msl — Mean sea‑level pressure (hPa).
• wind_speed_10m, wind_gusts_10m — Wind speed/gusts at 10 m (m/s).
• cloud_cover — Total cloud cover (%).
• temperature_2m_max, temperature_2m_min — Daily extrema (°C).
• rain_sum, snowfall_sum — Daily totals (mm).

The available variables depend on your chosen mode. Provide only the ones you need.

---

🧰 Troubleshooting

• No results for location: Try a more specific place name (e.g., "City, Country").
• Timezone mismatch: Set a specific IANA timezone instead of "auto".
• Empty dataset: Ensure your selected variables exist for the chosen mode.
• Rate‑limits: If running many jobs, space them out or batch your locations to avoid upstream throttling.