Why tempest_weather_q Fields Return null on Free Tier — and How to Build a Graceful Fallback Chain Without Duplicating Request Logic

When null Doesn’t Mean What You Think

Null in an API response can mean three different things: the data doesn’t exist for this location, the data exists but failed to load, or the data exists but you’re not on a tier that returns it. These are genuinely different situations, and conflating them will silently break your application in ways that are annoying to debug.

WeatherAPI returns nulls for fields that aren’t populated at a given plan level. Request air_quality=yes on the free tier and you’ll get a valid 200 with the air_quality block present but most sub-fields null. Same pattern with some astronomy precision fields and certain forecast-day aggregates that are plan-gated. The response structure doesn’t change — the fields are there, they just have no values.

That design makes sense for forward compatibility: your parsing code doesn’t break when you upgrade plans. But it also means field !== undefined isn’t a reliable guard. You need field !== null && field !== undefined, and even that isn’t the whole story.

The Three-Case Problem Most Fallback Logic Ignores

Here’s the breakdown worth building around:

  • Tier-gated null: The field exists structurally, returns null, and upgrading your plan would fix it. Retrying won’t help. Fetching from a secondary source won’t either.
  • Coverage null: The location is in a gap — ocean point with no nearby METAR, remote terrain beyond the station network. No plan tier fixes this. A secondary endpoint might.
  • Transient null: The model run was mid-ingest when your request hit, the upstream feed had a gap, or the hour you asked for fell outside the current model’s valid range. Retry after a short delay or shift your request window.

Most codebases treat all three as the same case, usually with a single fallback that retries immediately regardless. That burns quota on tier-gated nulls (retrying will never help) and misses coverage nulls where a different request strategy actually would.

Detecting Which Case You’re In

You can’t always tell from the response alone, but a few signals help.

For tier-gated nulls: if the same field is null across every location you test at different times, that’s a plan-level gate. Build a canary check at startup against a location you know has data — London, New York, Tokyo — and log which fields come back null. If your canary shows null on air_quality.us-epa-index for central London at noon, it’s not a data problem.

For coverage nulls: compare the station_id in the response against what you know about the location’s proximity to reporting infrastructure. If the returned station is 60+ km away, treat marginal or sensitive fields — visibility, cloud ceiling derivatives, humidity precision — with suspicion. NOAA’s station density data for the region is a useful sanity check. We cross-reference this against our own METAR ingestion view when something looks off.

For transient nulls: check last_updated_epoch against current time. An observation timestamp more than 90 minutes stale usually means the upstream feed had a gap. That’s retry territory.

Building the Fallback Chain Without Duplicating Request Logic

The temptation with fallbacks is to write parallel code paths: primary request logic, then a copy-paste of that logic with slightly different parameters. This gets messy fast, especially when you need to merge partial results from two different response shapes.

A cleaner pattern is a single request function that accepts a field-requirement spec, plus a resolver chain that iterates through sources in priority order and stops when the spec is satisfied:

type FieldSpec = {
  required: string[];   // must be non-null to accept this response
  optional: string[];   // grab if present, don't fail without
};

async function resolveWeather(location: string, spec: FieldSpec): Promise<WeatherResult> {
  const sources = [
    () => fetchForecast(location, { air_quality: true }),
    () => fetchCurrent(location),
    () => fetchNearestStation(location, { radius_km: 50 })
  ];

  let merged: Partial<WeatherResult> = {};

  for (const source of sources) {
    if (specSatisfied(merged, spec.required)) break;
    const result = await source();
    merged = { ...result, ...filterNonNull(merged) }; // existing non-nulls win
  }

  return merged as WeatherResult;
}

specSatisfied checks that every field in required is non-null in the current merged object. filterNonNull strips nulls from the existing result so they don’t overwrite real data from a later source. The request logic stays in one place and the fallback behavior is explicit and testable — you can mock the source functions and exercise the merge logic without hitting the API.

Where Caching Interacts With Fallback Chains

If you’re caching responses — and on free tier with limited quota you should be — the fallback chain needs to know whether a cached response had its required fields satisfied or was itself a partial result from a fallback source.

The fix is easy to skip: cache the metadata alongside the response. Store which fields were null, which source filled each field, and when the entry was written. When you serve from cache, re-run specSatisfied against the stored null map before deciding whether to pass it through or trigger a fresh chain.

Cache a tier-gated null result with a 10-minute TTL and don’t track why it was null, and you’ll serve null to every downstream consumer for those 10 minutes even if your plan just upgraded. Storing null_reason: "tier_gated" alongside the cached entry makes selective invalidation possible when account state changes.

A Note on Plan State as Shared Config

The tier-detection canary is worth running once at startup, not on every request. Store the result as application config — a set of known-unavailable fields — and use it to short-circuit fallback attempts that wouldn’t help anyway.

Something like PLAN_CAPABILITIES = { air_quality: false, marine: false } set at boot from the canary result, then checked before even attempting a request branch that relies on those fields. This saves round trips and makes the behavior explicit rather than discovered under production load. It also documents your plan constraints in a way that’s visible to other developers working in the codebase — which matters more than it sounds if the project outlives the person who originally set up the integration.

The Real Limit Here

None of this fallback logic recovers data that genuinely doesn’t exist. If a location is in a station coverage gap — remote Scottish Highlands, mid-Pacific coordinates, sparse monitoring areas in central Africa — no amount of retry or source-switching produces a real current observation. The honest thing is to surface that to the user: “conditions estimated from the nearest station, 45 km away” is more trustworthy than a silently interpolated number with no caveat attached.

When we built our METAR station-selection logic, the goal was to avoid fooling ourselves about what “representative” actually means at a given coordinate. The same principle applies to fallback chains: know what your data actually covers before deciding how much you trust it.

Run the canary check, log your plan’s null map, then look at which fields your application actually fails on in production. Tier-gated nulls and coverage-gap nulls show up as distinct patterns in your logs if you’re capturing null rates by field name alongside your API call records — and once you can see the difference, the right fix for each becomes obvious.

Scroll to Top