A planned API for observations and coverage.

The interface is designed to return the same structured record the product uses: place, time, movement, coverage, source, and related measures. The contract below is planned and will be validated with the product.

The endpoints

Ask for coverage before you ask for data

Verb	Path	What comes back	Key
GET	/v1/places	The places you may ask about, and whether each can answer today	Required
GET	/v1/coverage	How much of a window was actually seen. Ask this before you ask for data.	Required
GET	/v1/observations	Rows in the fourteen columns, for one place and one window	Required
GET	/v1/pylons/{id}	What one pylon is, who approved it, and what it keeps	Not needed
GET	/v1/log	The public request log, granted and refused alike	Not needed

A gap on the wire

The response that matters most

Missing coverage is part of the response.

GET /v1/coverage?place=RS-0119-C&from=2026-08-01&to=2026-08-15

{
  "place_id":       "RS-0119-C",
  "window_hours":   336,
  "observed_hours": 286,
  "coverage_state": {
    "seen":          286,
    "sensor_down":    50,
    "not_built":       0,
    "obscured":        0,
    "out_of_service":  0
  },
  "can_answer":     "partial",
  "why":            "lidar failed 2026-07-30, counts continue, speed does not"
}

The sample shows how an unavailable sensor period can be returned beside the observation window. A client can check coverage before using the movement record.

This is an illustrative contract, not a live production response.

Outside the API

Structured records and explicit boundaries

What the API will not return.

A name, face match, plate number, or identity index
A path stitched together after our own cameras lose sight of it
A raw image or video frame. The movement API returns structured records; any imagery is handled separately.
A zero standing in for an hour we didn't watch

Separate imagery, if offered for a defined use, follows its own access and retention terms outside the movement-record API.