weather-observation-fetching

# Weather Observation Fetching

Overview

Retrieve measured surface and upper-air weather reports without losing station

identity, observation time, units, raw values, or provider quality flags. Pick

the source by observation type and retention need, then validate the returned

records before normalization.

This skill covers METARs, historical surface observations, radiosondes, and

station metadata. It excludes model output, radar volumes, and satellite

imagery.

When to Use This Skill

- A task needs recent METAR observations for named stations or a small region.

- Historical hourly or synoptic surface data is needed from NOAA NCEI.

- A sounding workflow needs observed radiosonde profiles rather than model

profiles.

- Station identifiers, relocations, instruments, or metadata must be resolved.

- A fetch returned duplicate, stale, unit-ambiguous, or quality-flagged values.

Do not use forecast products as observations, and do not substitute a nearby

model grid point for a missing station report without explicit approval.

Choose the Source

| Need | Preferred source | Notes |

| --- | --- | --- |

| Recent aviation surface reports | NOAA Aviation Weather Center Data API | Query a small station/time set; use published cache files for bulk current data. |

| Historical global surface reports | NOAA NCEI Integrated Surface Database (ISD) | Preserve USAF/WBAN identity, units, and QC fields. |

| Historical or recent radiosondes | NOAA NCEI IGRA | Use the station inventory and retain level and QC metadata. |

| Station history and identifier changes | NOAA NCEI station history/HOMR | Resolve moves, renames, and observing-platform changes. |

Prefer an existing project adapter when it already handles the provider's

schema, retries, and cache. Record the exact endpoint or archive object used.

Define the Observation Request

Resolve these values before fetching:

- observation type and variables;

- station identifier system, not just the identifier string;

- start and end instants in UTC, including interval inclusivity;

- maximum acceptable observation age;

- raw, decoded, or both output forms;

- required quality flags and policy for rejected values;

- output units and missing-value representation;

- cache location and retention.

For spatial queries, also define the search geometry, distance limit, and how a

station is selected. Return the selected station and distance rather than

silently using the nearest report.

Fetch Recent METARs

The Aviation Weather Center exposes machine-readable METAR data under

`/api/data/metar`. Send a descriptive user agent, keep the query narrow, and

handle a valid `204 No Content` separately from an error.

import json
from urllib.error import HTTPError
from urllib.parse import urlencode
from urllib.request import Request, urlopen


def fetch_metars(stations, hours=2):
    station_ids = sorted({station.strip().upper() for station in stations})
    if not station_ids or any(len(station) != 4 for station in station_ids):
        raise ValueError("use one or more four-character ICAO station IDs")
    if not 1 <= hours <= 24:
        raise ValueError("hours must be between 1 and 24 for this narrow query")

    query = urlencode({
        "ids": ",".join(station_ids),
        "format": "json",
        "hours": hours,
    })
    request = Request(
        f"https://aviationweather.gov/api/data/metar?{query}",
        headers={"User-Agent": "weather-observation-fetching/1.0 contact@example.org"},
    )
    try:
        with urlopen(request, timeout=30) as response:
            if response.status == 204:
                return []
            records = json.load(response)
    except HTTPError as exc:
        if exc.code == 429:
            raise RuntimeError("AWC rate limit reached; honor Retry-After") from exc
        raise

    if not isinstance(records, list):
        raise RuntimeError("unexpected METAR response shape")
    return records

Replace the example contact address with