Zasady użycia API

Reguły korzystania z publicznego API teryt24.pl. Obowiązują każdy klient — z kluczem i bez. Wzorem dla tego dokumentu jest polityka użycia Nominatim (OSMF).

Limity

Bez klucza: 60 zapytań na minutę na adres IP. Limit jest współdzielony przez wszystkich anonimowych klientów za jednym adresem (NAT, VPN, wspólny serwer) — to kontrakt zgodności zachowań z pacjenteo i pozostaje niezmieniony.
Z kluczem API: limit przypisany do klucza (ustalany indywidualnie), w osobnym kubełku — ruch pod kluczem nie konkuruje z anonimowym.
Przekroczenie limitu odpowiada HTTP 429 z nagłówkiem Retry-After — prosimy go respektować zamiast ponawiać natychmiast.
Odpowiedzi GET niosą Cache-Control: max-age=86400 oraz ETag. Cache'owanie po stronie klienta jest oczekiwane — dane rejestrów zmieniają się najwyżej raz na dobę.

Identyfikacja

Prosimy, aby każdy klient identyfikował się na co najmniej jeden ze sposobów:

Własny nagłówek User-Agent nazywający aplikację (np. moj-aplikator/1.2 (+https://przyklad.pl)). Domyślne User-Agenty bibliotek HTTP (axios/1, Go-http-client/1.1, python-requests) opisują bibliotekę, nie aplikację — i nie są uznawane za identyfikację.
Nagłówek X-API-Key z kluczem otrzymanym od operatora (niżej).

Klienci przeglądarkowi są przypisywani automatycznie na podstawie nagłówków Origin/Referer. Co dokładnie widzi serwer o Twoich zapytaniach, pokaże Ci GET /v1/whoami.

Klucze API

Klucz identyfikuje integrację w statystyce ruchu operatora i daje jej własny limit. Wystąp o niego przez formularz wniosku, podając:

nazwy i adresu aplikacji lub firmy,
kontaktu do osoby odpowiedzialnej,
przybliżonego wolumenu (zapytania/minutę i dobę) oraz który zestaw endpointów wykorzystujecie.

Klucz jest pokazywany jednorazowo przy wystawieniu — przechowywany jest wyłącznie jego skrót, więc operator nie może go odtworzyć. Traktujcie go jak hasło: nie umieszczajcie go w repozytorium ani w kodzie klientowym widocznym w przeglądarce. Klucz można unieważnić w każdej chwili — od tej chwili zapytania z nim odpowiadają 401.

Pytania, prośby o klucz API i zgłoszenia nadużyć: [email protected].

Dane i atrybucja

API jest kompilacją rejestrów publicznych. Korzystając z wyników, prosimy podawać źródła — w przypadku GeoNames jest to wymóg licencji:

GUS TERYT (SIMC, TERC, ULIC) — miejscowości, podział administracyjny, ulice

Źródło: Główny Urząd Statystyczny (GUS), rejestr TERYT — eteryt.stat.gov.pl

Punkty adresowe PRG (GUGiK) — walidacja adresów i geokodowanie

Źródło: Główny Urząd Geodezji i Kartografii (GUGiK), Państwowy Rejestr Granic — geoportal.gov.pl

Kody pocztowe i współrzędne — GeoNames

Data © GeoNames (geonames.org), licensed under CC BY 4.0 — https://creativecommons.org/licenses/by/4.0/

Uwaga: to nieoficjalne opracowanie rejestrów publicznych. Serwis nie jest produktem GUS ani GUGiK i nie zastępuje rejestrów źródłowych — tam, gdzie liczy się pewność urzędowa, prosimy korzystać z oryginalnych źródeł.

Zabronione użycie

Następujące zastosowania są zabronione i skutkują zablokowaniem adresu lub klucza:

Zbiorowe pobieranie (scraping) — systematyczne przechodzenie rejestru, zapytania siatkowe (reverse w regularnej siatce), pobieranie pełnych list miejscowości, ulic czy kodów. Dane źródłowe są publicznie dostępne — prosimy je pobierać z nich, nie przez to API.
Odsprzedaż lub dalej-udostępnianie API — wystawianie tego serwisu jako własnego API, proxy dla aplikacji trzecich albo gotowy „connector" w platformach no-code/low-code.
Dzielenie jednego klucza między niepowiązane produkty — każda integracja dostaje własny klucz (za darmo).
Obchodzenie limitów — rotacja adresów IP, rozpraszanie zapytań po wielu kluczach, klienty pomijające Retry-After.
Autouzupełnianie przy każdym klawiszu w przeglądarce z pominięciem cache — dla tego służy Cache-Control i lokalny cache odpowiedzi.

Dostępność i zmiany

Usługa jest w fazie beta i działa best-effort — bez gwarancji SLA. Zasady mogą się zmienić; istotne zmiany limitów dla istniejących kluczy będą komunikowane po kontakcie zapisanym przy wydaniu klucza. Limit bezkluczowy (60/min/IP) nie zostanie obniżony bez zapowiedzi.

Kontakt

Pytania, prośby o klucz API i zgłoszenia nadużyć: [email protected].

Summary (English)

Keyless: 60 requests/min/IP, shared by all anonymous callers behind one address. Keyed: an individually assigned limit in its own bucket.
Identify yourself: a custom User-Agent naming your application and/or an X-API-Key. Stock library user agents do not count. GET /v1/whoami shows what the server sees.
Keys are issued manually by the operator on request (application form at /key-request); the plaintext is shown once and stored hashed. Treat it like a password.
Client-side caching is expected (responses carry Cache-Control: max-age=86400 and ETag).
Attribution: GUS TERYT and GUGiK PRG are public registers — cite the source; the postal-code data is GeoNames under CC BY 4.0, where attribution is mandatory.
Prohibited: bulk scraping or systematic queries, reselling or re-exposing the API, one key across unrelated products, circumventing limits (IP rotation, ignoring Retry-After). Violations lead to blocking.
Best-effort beta service, no SLA; this policy may change — the keyless limit will not be lowered without notice.