---
title: "`GET /v1/weather/frames`: the kept NOAA GFS forecast runs and their frame paths."
method: GET
path: "/v1/weather/frames"
tags: ["live"]
---

# \`GET /v1/weather/frames\`: the kept NOAA GFS forecast runs and their frame paths.

`GET /v1/weather/frames`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/v1/weather/frames`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `api_key`

The NOAA GFS forecast frames MapMap processes for the map: kept runs (newest first), each frame's valid time and file paths, how each field's PNG bytes decode (`encodings`), a `base` URL the paths resolve against and a `tiles` template for the pressure-line and rain/temperature tile ids. A forecast, not an observation; derived from NOAA GFS and modified by MapMap; no endorsement by or affiliation with NOAA is implied. Freshness is a field (`ok`, `stale`, `unknown`), never an error. When the key is sent as `?api_key=`, the same key is stamped onto `base` and `tiles`. One Standard unit per request; a browser (`maps`) key may call it.

## Query parameters

- `run` string
- `latest` integer

## Response `200`

The frame manifest

- WeatherFramesResponse: `GET /v1/weather/frames` answer.
  - `age_s` integer, nullable: Seconds since `generated_at`. `null` with no manifest.
  - `attribution` object, required: The credit, verbatim from the manifest.
  - `base` string, required: Frame paths below resolve against this URL.
  - `encodings` object, required: How each field's PNG bytes decode, verbatim from the manifest.
  - `generated_at` string, nullable: The manifest's own generation time (RFC 3339). `null` with no manifest.
  - `label` string, required: Forecast, not an observation.
  - `model` WeatherModel, required: The model behind the frames.
    - `frames_per_run` integer, nullable: Frames in the newest listed run. `null` when no run is listed.
    - `horizon_h` integer, required: Hours covered by a run.
    - `id` string, required: Always `gfs`.
    - `resolution_deg` number, double, nullable: Grid spacing, degrees (from the manifest).
    - `step_h` integer, required: Hours between frames.
  - `note` string, required: The modification and no-endorsement note.
  - `processed_by` string, required: Always `MapMap`.
  - `runs` WeatherRun[], required: Kept runs, newest first.
    - `frames` object[], required: The manifest's frame records verbatim: `hour`, `valid_at`, `wind`, `rain`, `temp`, `isobars`, the `*_png` paths, `half` and `gateway`. Paths resolve against `base`.
    - `generated_at` string, nullable: When the box finished publishing the run.
    - `run` string, required: The run's model time (RFC 3339).
    - `run_id` string, required: The run's directory name, `YYYYMMDDHH`.
  - `status` string, required: `ok`, `stale` or `unknown`.
  - `threshold_s` integer, required: The age after which the manifest reads `stale`, seconds.
  - `tiles` string, required: Tile URL template for the `gateway` ids on each frame (`rain`, `temp`: `png`; `isobars`: `mvt`).

## Other responses

- `400`: `invalid-run` or `invalid-latest`. Not billed
- `404`: `run-not-found`. Not billed
- `501`: Weather frames not enabled (`SN_WEATHER_DIR` unset). Not billed

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)