API reference

1. Overview & conventions

Base URL and media types

Conventions

• Timestamps are RFC 3339 strings (e.g. 2026-07-05T14:02:00Z).
• Enum values render as their proto names (WILDFIRE, ACTIVE, SEVERE). Query parameters accept them case-insensitively, and layer parameters additionally accept the lowercase layer slugs used in .geojson paths (wildfire).
• Repeatable filters: parameters documented as repeatable may appear multiple times — ?layer=wildfire&layer=evacuation.
• Pagination is cursor-based on the event lists — events, events/{id}/history, and history: pass the opaque nextPageToken from a response as the page_token query parameter on the next request (base64 keyset cursors; treat them as opaque). The directory lists — places, sources, and scanners — are not paginated: each returns its complete set in one response by design (a bounded, slowly-changing directory), with no nextPageToken. Read them whole; don't build paging logic for them.
• Query parameters stay snake_case regardless of response casing: severity_min, page_token, page_size (camelCase forms are also accepted).
• ETags: most read endpoints carry a weak ETag; a conditional request with a matching If-None-Match gets 304 Not Modified and skips the work. Coverage: events/{id} + .../history, the events and history lists, places + places/{place}, and the .geojson layers (body-hash). Not yet instrumented: conditions, sources, places:resolve, scanners, and summary. Independently, every proto RPC carries Cache-Control: public, max-age=30, so a proxy/CDN may serve any of them up to 30 s stale (the .geojson layers use max-age=60).
• Errors from the proto RPCs are gRPC-standard {code, codeName, message, details} alongside the mapped HTTP status; the one hand-built endpoint (.geojson) emits the older google.rpc.Status shape ({code, message, details}, no codeName):

HTTP/1.1 404 Not Found
Content-Type: application/json

{"code": 5, "codeName": "NOT_FOUND", "message": "event not found"}

code is the numeric gRPC status code (5 = NOT_FOUND, echoed as codeName). Clients should key on the HTTP status and surface message.

• Canonical client sort for events: severity descending, then observedAt descending.
• Places are addressable by slug or id: ebbetts-pass and area:ebbetts-pass both work anywhere a {place} appears. Slugs are globally unique (§4).

CORS

All /api/v1 endpoints are served with open CORS — any origin can fetch them from a browser. This site is itself an unprivileged client of that same surface: every number on every page here is a same-origin browser fetch you can replay with curl (see the footer of any page).

2. Endpoint reference

Two idioms, one rule: entities (events, places, sources, conditions, scanners) are global collections filtered by query parameter; place-derived documents (summary, map layers) nest under the place path. The two hot paths — summary and map layers — take no query string at all, so CDN cache keys stay clean.

Every entry expands to its parameter table and example requests. The examples are not illustrations: press RUN and the page fetches that exact URL live and prints the real response, status, timing and byte count. An example that has gone stale therefore fails in front of you rather than quietly misleading you.

3. The Event envelope

Every discrete occurrence is one grid.v1.Event message. The common envelope is identical across layers — a client can render any event's card from headline / severity / provenance / observedAt without knowing its kind. Typed per-kind data lives in exactly one detail block.

Fields, beside a live record

Every field

Detail blocks (the oneof)

Each block carries only kind-specific fields. Anything already in the envelope is not repeated: the incident/alert type is category, the human location is areaLabel, the short line is headline, the sending office is provenance.sourceName, and the source page is canonicalUrl.

Unit-bearing fields name their unit (depthKm). A fire_weather detail slot is reserved in the schema but fire weather is condition-backed (a map layer, not an event stream). The mesh block's telemetry is the last-heard signal state and is volatile — it never mints a new event revision (only a node's identity, role, name, location, or status does). For "when did this node last advertise", the trustworthy answer is the event's observedAt (when the Grid last heard it); telemetry.lastAdvertAt is the node's self-reported stamp and is diagnostic only (mesh node clocks skew). Slots are also reserved for future layers: power, gauge, air_quality, announcement.

Enum: Layer

road_segment and chain_control are condition-backed map-layer slugs only — they are projections of live road state, not Layer enum values, and never appear in /api/v1/events.

Enum: Severity (the canonical scale + color ramp)

One comparable scale across every source. It expresses response urgency to the public, not physical magnitude — an Evacuation Order (EXTREME) intentionally outranks an M5 earthquake (SEVERE). Rank equals the enum value. Always pair the color with the text label — color is never the only signal.

There are two ramps, not one: the same severity resolves to a print-weight colour on paper and a lighter, foreground-tuned one inside the black data panes, because no single value is legible on both. Ranks and enum names are identical across them — only the rendering differs, and the swatch is only ever a second signal beside the always-present text label.

Enum: EventStatus (lifecycle)

SCHEDULED ──▶ ACTIVE ──▶ RESOLVED   (upstream confirmed over)
                   └──▶ EXPIRED    (aged out; upstream went quiet)

Every status transition writes a revision — the all-clear is part of history. By default /api/v1/events returns only ACTIVE,SCHEDULED; closed events remain queryable by passing status= explicitly and through /api/v1/history.

Geometry and the base64 note

Event.geometry is {geojson: bytes, bbox: {minLat, minLng, maxLat, maxLng}, centroid: {lat, lng}}. The geojson field is a raw RFC 7946 geometry object stored as proto bytes — protojson renders bytes as base64, so decode before parsing:

const g = event.geometry;                          // may be absent entirely
const geom = g?.geojson ? JSON.parse(atob(g.geojson)) : null;
// geom is an RFC 7946 geometry object — coordinates are [lng, lat]

bbox and centroid are always populated at ingest when geometry exists, so list views never need to decode. For map rendering, prefer the .geojson endpoints — the base64 field exists for detail views.

4. Places & the id scheme

Place ids are {kind}:{slug}. Slugs are globally unique, so every place is addressable by bare slug (ebbetts-pass) or full id (area:ebbetts-pass) anywhere a {place} path segment or place= parameter appears. Area slugs are short, stable ids (e.g. ebbetts-pass).

Each Place carries id, kind, name, slug, geometry, parentId. Parent links: towns point at their county; areas have no parent. /api/v1/places:resolve returns containing places ordered most-specific-first: SITE, EVAC_ZONE, TOWN, CORRIDOR, COUNTY, AREA.

5. The GeoJSON layer contract

Each /api/v1/places/{place}/map/{layer}.geojson response is one RFC 7946 FeatureCollection with a foreign top-level metadata member (allowed by RFC 7946, ignored by map libraries, available to clients that read it):

{
  "type": "FeatureCollection",
  "features": [ … ],
  "metadata": {
    "layer": "evacuation",
    "area": "ebbetts-pass",
    "generatedAt": "2026-07-05T15:42:11Z",
    "sourceStatus": "OK",             // OK | STALE | UNAVAILABLE
    "lastSourceUpdate": "2026-07-05T15:38:00Z",
    "attribution": "Cal OES / California County Governments — reference only",
    "sourceUrl": "https://protect.genasys.com/…",
    "schemaVersion": 1
  }
}

metadata.sourceStatus

Layers are fail-loud: a source error never becomes a fabricated clear state. The three states render differently and must not be collapsed:

The properties envelope

Every feature, in every layer, shares one common envelope — that is the unification. A client renders any feature's card from headline / severity / source / updatedAt without knowing its kind:

{
  "type": "Feature",
  "geometry": { "type": "Point", "coordinates": [-120.5402, 38.0674] },
  "properties": {
    // ---- common envelope (present on every feature) ----
    "id": "calfire:2026-salt-springs",   // globally unique, source-namespaced
    "layer": "WILDFIRE",                 // Layer enum name (same value as event.layer)
    "kind": "Wildfire",                  // human label
    "category": "active",                // source sub-type slug (free-form, lowercase)
    "severity": "SEVERE",                // unified scale, §3
    "severityRank": 3,                   // 0..4, for sort/color
    "headline": "Salt Springs Fire — 1,377 ac, 20% contained",
    "description": "…",                  // optional, long
    "status": "ACTIVE",                  // EventStatus enum name (lifecycle)
    "effective": "2026-07-05T14:02:00Z", // RFC 3339, nullable
    "expires": null,
    "updatedAt": "2026-07-05T15:40:00Z",
    "areaLabel": "Hathaway Pines & Avery",   // optional
    "source": {
      "id": "calfire", "name": "CAL FIRE",
      "url": "https://www.fire.ca.gov/incidents/…",
      "attribution": "CAL FIRE / FIRIS",
      "fetchedAt": "2026-07-05T15:42:10Z"
    },
    // ---- per-kind typed block (only the relevant one) ----
    "wildfire": { "acres": 1377, "containment": 20, … }
  }
}

• Per-kind data lives under a single namespaced key (wildfire, earthquake, evacuation, weather, incident, power, mesh) — consumers ignore kinds they don't handle; no field collisions.
• Coordinate order is [longitude, latitude] (GeoJSON axis order), WGS84, trimmed to 5 decimals (~1.1 m). Polygons are simplified to keep features small.
• Null geometry is valid (e.g. a county-wide advisory): the feature has "geometry": null with the same properties envelope. Exclude it from the map layer and render it as a full-width banner/list card sorted by severityRank alongside located features, showing headline, source.name, updatedAt, and source.url.
• URL fields are scheme-validated upstream: any upstream-sourced URL that is not https:///http:// is dropped before it reaches the response. Treat all upstream text (headlines, descriptions) as untrusted anyway.
• Unit-bearing fields name their unit (windGustMph, depthKm).
• layer has two forms, by role. As a value — properties.layer here, and event.layer / topEvents[].layer elsewhere — it is the UPPERCASE Layer enum name (WILDFIRE). As an address — the {layer} path segment, the ?layer= query value, and the metadata.layer / metadata.area echoes above — it is the lowercase slug (wildfire). One rule: values are enum names, URLs and the metadata block are slugs. Mesh-node presence is the one layer whose slug (mesh_node) is not just the lowercased enum name (MESH): as a ?layer= value the query accepts mesh (the enum name), mesh_node (the slug), and the legacy network — all resolve to the same layer. (Before 2026-07-25 this layer's enum was NETWORK; it was renamed to MESH, with network kept as a legacy query alias.)
• This endpoint is not in the OpenAPI spec. The .geojson layers are hand-built (RFC 7946 geometry doesn't model cleanly in proto3), so a client generated from the spec alone will be missing all eight map layers — integrate them from this section.

7. Source registry

Every event and every layer traces to one of these sources — the registry behind /api/v1/sources (live board: Sources). Each Source carries id, name, attribution, homepageUrl, pollIntervalSeconds, staleAfterSeconds, expireAfterSeconds, lastSuccessAt, lastAttemptAt, lastError, status. A source is STALE once its last success is older than staleAfterSeconds (default 3× its poll interval) and UNAVAILABLE on persistent failure.

A poller may update multiple source rows (the wildfire tick updates calfire + firis; the incidents tick updates chp + caltrans) — poller ≠ source. Poll intervals and staleness thresholds are server configuration; read the live values from /api/v1/sources rather than hard-coding this table.

Attribution requirements

• Display the attribution string (from Source.attribution, Event.provenance.attribution, or metadata.attribution on GeoJSON layers) wherever you render the data.
• Link the upstream: provenance.sourceUrl (events) / metadata.sourceUrl (GeoJSON) on records, homepageUrl on the source.
• Evacuation data must carry its reference-only framing and the Genasys link in every state (§6).