# Freshness and rate limits

# Freshness and rate limits

## How current the data is

Responses are cached at the edge with `Cache-Control: public, max-age=120,
stale-while-revalidate=300`. A district's change reaches most callers within
two minutes. The worst case is about seven minutes: a cached copy may be
served for two minutes, then served stale for up to five more while the edge
fetches a fresh one. Do not poll faster than once a minute; you will only
receive the same cached response.

Weather and air quality come from third parties and are `null` when those
sources have no usable reading. Everything else answers normally.

## Rate limits

Two ceilings, both measured over five minutes at the edge, both counting
cached responses:

| Ceiling        | Limit          | What happens                                                      |
| -------------- | -------------- | ----------------------------------------------------------------- |
| Per IP address | 200 requests   | `429` for the rest of the window.                                 |
| Per key        | 6,000 requests | `429` for the rest of the window, for every visitor of that site. |

A `429` carries `Retry-After: 300` and a JSON body with code `rate_limited`.
Your key's count is what your site's visitors send in total, because each
visitor's browser makes the request. A busy public page should fetch once
per page view at most, or fetch server-side and cache for a minute.

If your site outgrows a ceiling, tell your Stationworks contact; the limit
is ours to raise, not a hard property of the service.

## Where your key appears

The key travels in the query string on purpose, so a plain `fetch` from a
page works. It is publishable: anyone who copies it can spend your key's
quota, and nothing more. If that happens, ask for a new key.