Limity, klucze i identyfikacja
Bez klucza API obowiązuje 60 zapytań na minutę na adres IP — wspólny kubełek dla wszystkich anonimowych wywołań z jednego adresu. Po przekroczeniu endpointy odpowiadają HTTP 429 z nagłówkiem Retry-After (sekundy do zwolnienia kary) i X-RateLimit-*.
Klucz API (nagłówek X-API-Key, format t24_…) identyfikuje integrację i przenosi ją do osobnego kubełka z własnym limitem. Wystąp o klucz przez formularz wniosku — po zatwierdzeniu dostajesz mail z jednorazowym linkiem odbioru, a klucz pokazujemy tylko raz.
Oprócz klucza ustaw znaczący User-Agent (nazwa aplikacji zamiast domyślnego axios/1) — to, co serwer widzi o Twoich żądaniach, pokaże GET /v1/whoami, a klucz sprawdzi własne zużycie przez GET /v1/usage.
Udane GET-y niosą ETag i Cache-Control: public, max-age=86400 — powtórzone zapytanie z If-None-Match dostaje 304 bez treści, co oszczędza transfer po obu stronach.
GET /v1/whoami
Echo atrybucji żądania — nie jest cache'owane, bo odpowiedź jest per-wywołujący.
Sprawdź na żywo: /v1/whoami
Przykład
Bez klucza, z curl
curl "https://teryt24.pl/v1/whoami"Odpowiedź:
{
"apiClient": null,
"identified": false,
"clientClass": "server",
"userAgent": "curl/8",
"refererHost": null,
"originHost": null,
"country": "PL",
"policyUrl": "/usage-policy",
"rateLimit": { "max": 60, "windowMs": 60000, "scope": "per IP (keyless — see the docs on identifying yourself)" }
}| Status | Opis |
|---|---|
200 | What the service records about this request. |
401 | The presented X-API-Key is invalid or revoked. |
429 | Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. |
GET /v1/usage
Sumy i zero-wypełniona seria dzienna (UTC) żądań klucza. Bez klucza: identified:false z pustymi totals/perDay. unavailable:true oznacza nieudaną agregację (HTTP i tak 200).
Sprawdź na żywo: /v1/usage?days=30
| Nazwa | Wymagany | Opis |
|---|---|---|
days | — | Window length in days (1–90, default 30). A blank value falls back to the default. |
Przykład
Bez klucza (kształt odpowiedzi)
curl "https://teryt24.pl/v1/usage?days=30"Odpowiedź:
{
"apiClient": null,
"identified": false,
"windowDays": 30,
"rateLimit": { "max": 60, "windowMs": 60000, "scope": "per IP (keyless — see the docs on identifying yourself)" },
"generatedAt": "2026-10-18T14:37:57.265Z",
"totals": null,
"perDay": null,
"unavailable": false
}| Status | Opis |
|---|---|
200 | Successful response. |
401 | The presented X-API-Key is invalid or revoked. |
429 | Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. |
GET /v1/datasets
Skąd pochodzą dane i jak są świeże: per zbiór źródło, licencja, data źródłowa (z nazwy pliku GUS/GeoNames), moment publikacji na tej instancji, liczba wierszy z pomiaru i werdykt świeżości (status: ok | stale | unknown). lastAttempt pokazuje ostatną próbę odświeżenia — odrzucenie walidacją lub błąd jest widoczne, a wcześniej opublikowane dane nadal są serwowane. Odpowiedź nie jest cache'owana.
Sprawdź na żywo: /v1/datasets
Przykład
Przykład odpowiedzi (skrócony)
curl "https://teryt24.pl/v1/datasets"Odpowiedź:
{
"datasets": [
{
"id": "simc",
"title": "Localities (SIMC)",
"source": "GUS TERYT (eteryt.stat.gov.pl)",
"licence": "public register (GUS)",
"sourceDated": true,
"sourceFile": "SIMC_Adresowy_2026-06-12.csv",
"sourceDate": "2026-06-12",
"sourceAgeDays": 129,
"processingStartedAt": "2026-10-18T04:10:02.113Z",
"publishedAt": "2026-10-18T04:12:33.847Z",
"ingestAgeDays": 1,
"recordCount": 54123,
"recordCountAsOf": "2026-10-18T04:12:33.847Z",
"coverage": null,
"budgetDays": 183,
"stale": false,
"status": "ok",
"publishedWith": { "warnings": 0, "forced": false }
},
{
"id": "prg",
"title": "Address points (PRG)",
"source": "GUGiK EMUiA (opendata.geoportal.gov.pl)",
"sourceDated": false,
"sourceDate": null,
"coverage": "16/16 voivodeships · 8634512 address points",
"status": "ok"
}
],
"lastAttempt": { "startedAt": "2026-10-18T04:10:01.902Z", "finishedAt": "2026-10-18T04:12:33.847Z", "status": "success", "outcome": "published" },
"policyUrl": "/usage-policy",
"generatedAt": "2026-10-18T09:30:00.000Z"
}| Status | Opis |
|---|---|
200 | Per-dataset status, values only. |
429 | Rate limit exceeded (60 requests/min/IP) or a plan's monthly quota exhausted. Includes `Retry-After` and `X-RateLimit-*` headers; the body's `code` distinguishes the two kinds. |
Przeglądaj dane
Wniosek o klucz API (formularz):
Wszystkie endpointy /v1 zwracają JSON, obsługują CORS i są objęte dokumentem openapi.json. Interaktywna wersja tej referencji: /docs.
Dane: GUS TERYT, punkty adresowe PRG (GUGiK), kody pocztowe GeoNames — przez teryt24.pl z linkiem do zasad użycia. Użycie wyłącznie po stronie serwera jest zwolnione.