What “Historical Weather Data” Actually Means at the API Level
When developers say they want historical weather data, they usually mean one of three different things — and conflating them is where backtesting projects go wrong early.
The first is observed historical conditions: actual METAR or synoptic station readings, interpolated to your coordinate, covering the past. The second is historical forecast replays: what a model like GFS or HRRR was predicting at a given point in time, for a specific lead time ahead. The third is climatological normals: long-run averages, percentiles, or anomaly scores derived from decades of records. These are not interchangeable. A backtesting pipeline for a logistics app optimizing delivery decisions probably wants (1). A pipeline testing how well a forecast-driven pricing model would have performed wants (2). A pipeline benchmarking seasonal risk wants (3).
WeatherAPI’s /history.json endpoint gives you (1). It returns observed conditions — temperature, precipitation, wind, humidity, condition codes — for a past date, at hourly granularity. That’s what this post covers, because it’s what most developers reach for first and where the friction clusters.
The Date Range Reality Check
The history endpoint accepts a dt parameter for a single date, or dt plus end_dt for a contiguous range. The catch most people hit on their first bulk pull: a single request covers a limited window, so pulling twelve months of daily data isn’t one call — it’s a loop.
Here’s a minimal Python pattern that handles this without hammering the endpoint:
import requests
import time
from datetime import date, timedelta
API_KEY = "your_key_here"
LOCATION = "51.5074,-0.1278" # London
START = date(2024, 1, 1)
END = date(2024, 12, 31)
CHUNK_DAYS = 7
def fetch_history_chunk(start, end):
url = "https://api.weatherapi.com/v1/history.json"
params = {
"key": API_KEY,
"q": LOCATION,
"dt": start.isoformat(),
"end_dt": end.isoformat(),
}
r = requests.get(url, params=params, timeout=15)
r.raise_for_status()
return r.json()
current = START
all_days = []
while current <= END:
chunk_end = min(current + timedelta(days=CHUNK_DAYS - 1), END)
data = fetch_history_chunk(current, chunk_end)
for day in data["forecast"]["forecastday"]:
all_days.append(day)
current = chunk_end + timedelta(days=1)
time.sleep(0.5) # be polite to the endpoint
The sleep(0.5) isn’t just politeness. On free and lower-tier plans, burst rate limits are real. A tight loop pulling 52 weekly chunks back-to-back will likely get throttled partway through, leaving you with a partial dataset and an unclear error. Half a second between requests is cheap insurance.
The Station Consistency Problem Nobody Warns You About
Here’s the subtler issue: the station serving observations for your coordinate today is not necessarily the same station that served it six months ago. Stations go offline. New stations come online. Coverage areas shift. When you’re pulling a year of hourly data to calculate trends or run a regression, silent station switches mid-series are a real contamination risk.
The history response includes a nearest_area block in the location object. It won’t tell you explicitly which METAR station backed each hourly reading, but you can use the returned coordinates as a rough consistency check — if the resolved location jumps between requests, something changed upstream. It’s a blunt signal, not a precise audit trail.
This is one of the reasons we’re exploring historical bulk data licensing as a separate product path. A bulk export with consistent provenance metadata per reading is a genuinely different thing from assembling that same picture through repeated API calls. The API is optimized for point-in-time lookups, not forensic auditability across a year of station data.
Hourly vs. Daily: Which Granularity to Backtest Against
The history response gives you both: a forecastday array with a daily summary, and an hour array within each day with 24 hourly slots. The daily summary fields — maxtemp_c, mintemp_c, totalprecip_mm — are derived from the hourly readings, not independently sourced. So if your model uses daily inputs, the daily fields are fine. But if your model is sensitive to when within the day something happened (peak heat at 2pm vs. 6pm matters a lot for heat stress or demand forecasting), pull and store the hourly array. The daily summary will hide intraday structure your backtest actually needs.
Concretely: a solar energy model backtesting against daily.avgvis_km is probably fine. The same model backtesting against hourly irradiance patterns — using hour[].uv or hour[].cloud as proxies — needs the hourly array. You can’t reconstruct intraday shape from daily aggregates.
What the Condition Codes Are and Aren’t Telling You
Each hourly slot includes a condition object with a numeric code and a text description. These codes are WeatherAPI’s own mapping from raw METAR observations — we built and maintain that mapping, which means they’re internally consistent but not a direct match to WMO present weather codes or anything you’d find in a standard meteorological dataset.
For backtesting, this matters if your model was trained or calibrated against a different condition taxonomy. If you’re importing historical conditions into a pipeline that expects WMO codes or NWS categories, you need an explicit crosswalk. Code 1063 (“Patchy rain possible”) does not map cleanly to any other system’s “light rain” — the boundary conditions differ.
Where condition codes are genuinely useful in backtesting: broad binary classification. Was it raining or not? Snow? Fog? For that kind of labeling, the codes are reliable enough and save you from building your own precipitation-type classifier on top of raw precip_mm readings.
Quota Math Before You Start
Do the arithmetic before launching any multi-month pull. A year of daily history for a single location is 365 API calls pulled day-by-day, fewer with multi-day chunks. Ten locations is 3,650 calls minimum. On a free plan with a monthly call cap, a naive implementation will exhaust your quota before you’ve even explored the data.
Two things help. First, pull once and cache locally — SQLite or flat JSON files per location-date. Historical data doesn’t change, so there’s no reason to re-request it. Second, if your backtesting system reruns regularly (monthly retraining of a forecast model, say), structure your storage so you only ever fetch the delta — dates not already in your local store. The fetch-everything-fresh-each-run pattern creates quota problems that feel mysterious until you actually count the calls.
The Data Quality Gap That Will Bite You Eventually
Historical coverage is not uniform across the globe. For well-instrumented regions — most of Western Europe, North America, Australia — station density is reasonable and gaps are infrequent. For large parts of Central Africa, remote Central Asia, or small island territories, the nearest station may be far enough away that the returned reading is more interpolation than observation. The hourly granularity will feel artificially smooth as a result.
Smoothness is the tell. Real observed hourly data has noise — temperature doesn’t move in tidy increments every hour. If a historical pull for a remote location looks suspiciously uniform, it’s likely being filled from model output or a very distant station rather than a local observation. That’s still usable for backtesting, but a model calibrated on interpolated data should be interpreted differently than one calibrated on dense-network observations.
A practical check: pull the same date range for a location you know well and compare the hourly variance profiles. If the remote location shows significantly less intraday variance on temperature or wind, the underlying data source is different from what you’re assuming.
If your backtest depends on data quality holding up in a specific region, pull a sample week and examine it before building the whole pipeline around the assumption that you’re working with observation-quality data. Finding that out at the end is expensive.