> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tariffs.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Caching and limits

> How to use a free API without being the reason it stops being free.

Reading needs no key and costs nothing. What there is instead is a rate limit
and a set of cache headers, and the two are related: honour the headers and you
will essentially never meet the limit. An integration that needs more takes an
[API key](https://docs.tariffs.nlead.ch/keys.md).

## Caching

Every public read carries an `ETag` and a `Cache-Control` matched to how fast
that resource actually moves.

| Resource | `max-age` | Why |
| - | - | - |
| `/api/geo/*` | 24 hours | Supply-area geometry changes when federal boundaries do — once a year. |
| `/api/v1/*`, `/api/map/tariffs`, `/api/tariff/find` | 5 minutes | The dataset changes only when the collection pipeline runs. |
| Everything else under `/api/` | 1 minute | Drives the live screens; a reviewer's validation should show up promptly. |

All carry `stale-while-revalidate=600`, so a cache may keep serving while it
refreshes behind your reader's back.

### Revalidating

```bash theme={null}
# first request
curl -i "$TARIFF_API/api/v1/periods"
# → 200, ETag: W/"3f9a…"

# later
curl -i -H 'If-None-Match: W/"3f9a…"' \
  "$TARIFF_API/api/v1/periods"
# → 304 Not Modified, no body
```

Weak and strong forms compare as equal per RFC 9110, so `W/"x"` and `"x"` both
match. Any HTTP client library with caching enabled does this for you.

> [!TIP]
>
> The area geometry is 2.8 MB, or 734 kB gzipped, and it is the same file every
> time. Fetching it once per session instead of once per view is the single
> biggest thing most integrations can do.

### Compression

Responses over 1 kB are gzipped when you send `Accept-Encoding: gzip` — which
`curl --compressed` and every browser and HTTP library does by default.

### What is never cached

Everything behind the reviewer lock — the workbench, the review queue, the run
ledger, uploads — is served `no-store`. Those routes are not part of the public
API and are not in the reference.

## Rate limit

**120 requests per minute per address**, or your key's tier with an
[API key](https://docs.tariffs.nlead.ch/keys.md). Every response tells you where you stand:

| Header | |
| - | - |
| `X-RateLimit-Limit` | The ceiling in force. |
| `X-RateLimit-Remaining` | Requests left in this window. |
| `X-RateLimit-Reset` | Seconds until the window rolls. |
| `X-API-Tier` | The tier that served the request, when you sent a key. |

Over the limit, you get a `429` with `Retry-After`:

```json theme={null}
{
  "error": "rate_limited",
  "detail": "More than 120 requests in a minute from this address. The dataset is free — please cache it rather than poll it. Every response carries an ETag and a Cache-Control you can honour.",
  "limit_per_minute": 120,
  "retry_after_seconds": 37
}
```

The window is a fixed minute, not a rolling one, so a `429` never costs you more
than `retry_after_seconds`.

> [!NOTE]
>
> Loading the map fires several requests at once and stays far below the limit. If
> you are hitting it, you are almost certainly re-fetching something that has not
> changed — check whether you are sending `If-None-Match`.

### If you need more

Take the [bulk export](https://docs.tariffs.nlead.ch/guides/bulk.md) instead of iterating over operators. One
request replaces five hundred, and it is the access pattern the dataset is built
for. If you still need more, an [API key](https://docs.tariffs.nlead.ch/keys.md) raises the limit to 300 or more
requests a minute, and [webhooks](https://docs.tariffs.nlead.ch/webhooks.md) replace polling for changes.

## CORS

Reads are open to any origin, so you can call this API directly from a browser
with no proxy:

```js theme={null}
const BASE = "https://ch-el-tarif-db.azurewebsites.net";
const r = await fetch(`${BASE}/api/v1/periods`);
```

`GET`, `HEAD` and `OPTIONS` are allowed, from `*`, with no credentials —
`Access-Control-Allow-Credentials` is deliberately off, so a browser will never
attach a signed-in reviewer's session to a cross-origin call. `ETag` and the
rate-limit headers are in `Access-Control-Expose-Headers`, so your JavaScript
can read them.

## Availability

This is a single small instance with no SLA. It is kept up because the data is
being collected against regulatory deadlines, not because anyone has promised
you uptime. If your system must not stop when this does, take the bulk export
and serve from your own copy.

## Terms

The data originates from Swiss grid operators' own publications and from ElCom's
open data. Use it freely. If you republish figures, carry the
[provenance](https://docs.tariffs.nlead.ch/concepts/provenance.md) with them — a reader deserves to know whether
a number was confirmed by a person or read out of a PDF by a model.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.