Conditional requests

Metered GETs return an ETag. Send it back as If-None-Match to revalidate: if the data (and your query) are unchanged, you get 304 Not Modified with no body and no tokens charged. This works even at a zero balance, so polling for changes is free.

GET /v1/blocks/{geoid}/summary          → 200, ETag: "a1b2c3d4e5f6a7b8"
GET /v1/blocks/{geoid}/summary
    If-None-Match: "a1b2c3d4e5f6a7b8"   → 304 (0 tokens)

The ETag changes when either the underlying data vintage or your query changes. Treat it as an opaque validator: store it and echo it back verbatim.

Note

The isochrone routes carry their own long-lived, publicly cacheable ETags. One wrinkle: unlike the row-metered routes, an isochrone revalidation at a zero balance returns 429 tokens-exhausted rather than a free 304.