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.

GET /api/v1/places/{place}/summary

One fetch returns a place's current state. The GetPlaceSummary proto RPC (camelCase, like the rest) with the area mode, a cross-layer summary, per-domain statuses, top events, and a source-health sidecar. Carries the evacuation fail-loud invariant — activeEvacuations is int | null, and null means unknown, never zero (§6). Full response shape quoted in §6.

GET /api/v1/places/{place}/map/{layer}.geojson

One RFC 7946 FeatureCollection per layer, ready for MapLibre / Leaflet / OpenLayers. Full contract in §5. Cache-Control: max-age=60.

GET /api/v1/events

The cross-layer query: every discrete occurrence — wildfire, evacuation, weather alert, earthquake, road incident — through one surface. Returns EventList ({"events": [Event…], "nextPageToken": "…"}). Results are keyset-paginated in canonical order (severity desc, observedAt desc, id).

GET /api/v1/events/{id}

One Event (§3), current revision, as protojson. Ids are source-namespaced (calfire:2026-salt-springs, usgs:nc12345678) — take one from a /api/v1/events response. The event explorer links every row here.

GET /api/v1/events/{id}/history

The per-incident timeline: EventRevisionList — every revision of the event, newest first, each as {"revision": n, "observedAt": …, "ingestedAt": …, "event": Event}. A revision is written only when content actually changes (upstream re-stamps with identical content produce no revision), and lifecycle transitions — including the all-clear to RESOLVED/EXPIRED — are themselves revisions, so the record ends with the ending.

GET /api/v1/history

Cross-event archive and replay over all revisions — the after-action review query. Returns EventRevisionList.

GET /api/v1/places · /api/v1/places/{place}

The place directory (PlaceList / Place): areas, counties, towns, corridors — the id scheme is §4. Filters: kind (a PlaceKind name, e.g. COUNTY) and q (text filter on place names).

GET /api/v1/places:resolve

Point or address → containing places (PlaceList). Pass either lat + lng (WGS84 decimal degrees; pure point-in-polygon, no external calls) or address (one-line address, geocoded via the US Census geocoder, then point-in-polygon). Results are ordered most-specific-first: SITE, EVAC_ZONE, TOWN, CORRIDOR, COUNTY, AREA.

GET /api/v1/conditions

Conditions, not events: the GetConditions RPC returns current weather for the monitored locations plus the region's fireWeather classification (normal / elevated / red-flag, derived only from authoritative NWS products). Optional ?place= filters locations to a place's bounding box. Per-location alerts are dropped — weather alerts are events: query /api/v1/events?layer=weather_alert. There is no roads passthrough either: road conditions are the road_segment and chain_control .geojson map layers, and road incidents are events (/api/v1/events?layer=road_incident).

GET /api/v1/scanners

Broadcastify scanner-feed configuration (ScannerList) — link-out only, no audio rebroadcast. Filter with ?place=.

GET /api/v1/sources

The provenance and health registry behind every sourceStatus in the system (SourceList): per source, its poll interval, last successful fetch, last attempt, last error text, and derived status OK | STALE | UNAVAILABLE. Registry contents in §7; live board on the Sources page.

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

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.

Hexes are the canonical dark-console ramp (--sev-* in the design system); 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 / WFIGS",
      "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, 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 + wfigs; 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).