Guides

Weather observations

Three observation sources feed the same canonical schema. The SDK fetches in parallel, tags every row with its source, and writes a parquet/JSON cache; on overlap it applies a deterministic client-side dedup tiebreak. Every row carries its source identity — you can branch on it.

The three sources

Tiebreak	Source	Endpoint	Window	Notes
3	AWC	`aviationweather.gov/api/data/metar`	Last 168h	Live, lowest-latency. CORS-allowed
2	IEM	`mesonet.agron.iastate.edu/cgi-bin/request/asos.py`	Full history	Near-real-time mirror, multi-year archive
1	GHCNh	`ncei.noaa.gov/oa/global-historical-climatology-network/...`	Full history	Quality-flagged archive

When fetched feeds overlap on a (station, observed_at) tuple, a client-side dedup tiebreak in your process keeps one row: AWC > IEM > GHCNh.

See Data sources for the rationale (it’s about raw-as-reported, not absolute correctness).

Fetch one window

The high-level call is obs():

Python
TypeScript

1
from mostlyright.weather import obs
2

3
rows = obs("KNYC", "2025-01-06", "2025-01-12")
4
print(rows[0])
5
# {
6
#   "station": "KNYC",
7
#   "observed_at": "2025-01-06T00:51:00Z",
8
#   "source": "awc.live",
9
#   "temp_c": 0.5,
10
#   "temp_f": 33,
11
#   "raw_metar": "KNYC 060051Z 35008KT 10SM CLR M01/M05 A3020",
12
#   ...
13
# }

1
import { obs } from "@mostlyrightmd/weather";
2

3
const rows = await obs("KNYC", "2025-01-06", "2025-01-12");
4
console.log(rows[0]);

Default routing — auto-router picks exact_window for ≤7-day windows, warm_cache for larger. See Ingest strategies for the routing logic.

Single-source query

1
const rows = await obs("KNYC", "2025-01-06", "2025-01-12", { source: "iem" });
2
// Every row.source === "iem.archive"

Pinning to one source forces exact_window (single-source can’t honor the multi-source merge that warm_cache enables).

Observation schema

The canonical observation row (schema.observation.v1):

1
{
2
  "station": "KNYC",
3
  "observed_at": "2025-01-06T00:51:00Z",
4
  "source": "awc.live",
5
  "observation_type": "METAR",
6
  "raw_metar": "KNYC 060051Z 35008KT 10SM CLR M01/M05 A3020",
7

8
  "temp_c": 0.5,
9
  "temp_f": 33,
10
  "dewpoint_c": -2.0,
11
  "dewpoint_f": 28,
12
  "wind_speed_kt": 8,
13
  "wind_direction_deg": 350,
14
  "wind_gust_kt": null,
15
  "pressure_inhg": 30.20,
16
  "precip_mm_1h": 0,
17

18
  "sky_cover_1": "CLR",
19
  "sky_base_1_m": null
20
}

See Observation schema for the full field list, units, and dtype conventions.

Source identity

Every row carries its source on the source field:

AWC live rows: "awc.live"
IEM archive rows: "iem.archive"
GHCNh rows: "ghcnh"
Plus .live variants on live.stream() (see Live streaming)

You can branch on this without parsing strings:

1
for row in rows:
2
    if row["source"].endswith(".live"):
3
        # Live feed; might still be revised
4
        ...
5
    else:
6
        # Archive; final
7
        ...

Raw METAR

raw_metar is the exact text the station broadcast (for AWC + IEM). GHCNh rows have raw_metar: null (the archive carries decoded values only). MetPy can re-parse the raw METAR if you need fields the SDK doesn’t surface:

1
from metpy.io import parse_metar_to_dataframe
2
import pandas as pd
3

4
raw_rows = obs("KNYC", "2025-01-06", "2025-01-12")
5
metars = [r["raw_metar"] for r in raw_rows if r["raw_metar"]]
6
metpy_df = pd.concat([parse_metar_to_dataframe(m) for m in metars])

Daily extremes

For per-day max/min temperature rollups (which is what Kalshi NHIGH/NLOW settles on):

Python
TypeScript

1
from mostlyright.international import daily_extremes
2

3
days = daily_extremes("KNYC", "2025-01-06", "2025-01-12")
4
print(days[0])
5
# {
6
#   "station": "KNYC",
7
#   "date": "2025-01-06",
8
#   "high_f": 37,
9
#   "low_f": 23,
10
#   "high_at": "2025-01-06T17:51:00Z",
11
#   "low_at": "2025-01-06T06:51:00Z",
12
# }

1
import { dailyExtremes } from "@mostlyrightmd/weather";
2

3
const days = await dailyExtremes("KNYC", "2025-01-06", "2025-01-12");
4
console.log(days[0]);

The TS port uses the station’s IANA tz from the registry to bucket observations by station-local date. Integer-°F precision matches Kalshi’s settlement rounding for US stations.

Cache

Observations cache as per-month parquet (Python) or JSON (TypeScript) under ~/.mostlyright/cache/observations/{station}/{year}/{month}.{parquet|json}. The current LST month is skipped (incomplete data is never cached).

See the Cache guide for the full layout, skip rules, and schema-version invalidation.

Per-source adapters

If you need to call the source-specific fetcher directly:

1
from mostlyright.weather.catalog import get_adapter
2

3
awc = get_adapter("awc.live")     # AwcAdapter
4
iem = get_adapter("iem.archive")  # IEMAdapter
5
ghcnh = get_adapter("ghcnh.archive")  # GhcnhAdapter
6
cli = get_adapter("cli.archive")  # CliAdapter (climate, not observations)
7

8
rows = awc.fetch_observations("KNYC", "2025-01-06", "2025-01-12")

Unknown sources raise DataAvailabilityError(reason="model_unavailable").