Autouzupełnianie — jedno zapytanie, cały katalog
GET /v1/autosuggest scala cztery wyszukiwania (miasta, miejscowości, ulice, kody pocztowe) w jedną listę podpowiedzi. Ranking jest ujednolicony: tier dopasowania (exact > prefix > alias > fuzzy) dominuje, ważność realna (ludność, punkty adresowe) porządkuje w obrębie tieru, a opcjonalny fokus lat/lon przesuwa wyniki wg odległości, nie zawężając ich.
Każda warstwa korzysta z dokładnie tego wyszukiwania, które serwuje jej dedykowany endpoint; warstwa z brakującym zbiorem danych wnosi nic i jest nazwana w layersDegraded. Wiersze odpowiedzi to suma rozłączna na polu type, a label to gotowy do wyświetlenia opis.
GET /v1/autosuggest
Warstwy zawęża layers= (city,locality,street,postal); limit 1–20, domyślnie 8.
Sprawdź na żywo: /v1/autosuggest?q=warsz&limit=6
| Nazwa | Wymagany | Opis |
|---|---|---|
q | ✓ | Search query; diacritics- and punctuation-insensitive. |
layers | — | Comma-separated subset of city,locality,street,postal (default: all). An unknown layer name is a 400. |
limit | — | Maximum suggestions (1–20, default 8). |
lat | — | WGS84 latitude of the optional focus point (with lon): reorders within a tier by distance, never restricts. A blank value is treated as absent. |
lon | — | WGS84 longitude — must be given together with lat. |
rm | — | Optional 2-digit rodzaj filter for the place layers. |
province | — | Optional 2-digit TERC voivodeship filter (place layers). |
county | — | Optional 4-digit TERC filter (place layers). |
municipality | — | Optional 6-digit TERC filter (place layers). |
aliases | — | Opt-in exonym fallback for the place layers ('Danzig' finds Gdańsk). |
Przykład
Wszystkie warstwy naraz
curl "https://teryt24.pl/v1/autosuggest?q=warsz&limit=6"Odpowiedź (skrócona — pokazano pierwsze wiersze):
{
"suggestions": [
{ "type": "city", "id": "0988796", "name": "Warszawa", "label": "Warszawa, Białołęka, Warszawa, MAZOWIECKIE", "score": 3006231, "province": "MAZOWIECKIE", "county": "Warszawa", "municipality": "Białołęka", "lat": 52.229830465613446, "lon": 21.011738848895394, "population": 1702139 },
{ "type": "locality", "id": "0918130", "name": "Warszawa", "label": "Warszawa, Mokotów, Warszawa, MAZOWIECKIE", "score": 3006231, "rm": "95", "typeLabel": "dzielnica m.st. Warszawy", "province": "MAZOWIECKIE", "county": "Warszawa", "municipality": "Mokotów", "lat": 52.22977, "lon": 21.01178, "population": 1702139 },
{ "type": "street", "id": "23679", "name": "ul. Warszawka", "label": "ul. Warszawka, Dubeczno", "score": 3000000, "cecha": "ul.", "city": "0103390", "localityName": "Dubeczno", "addressCount": 0, "localityCount": 0, "lat": 51.44403215560712, "lon": 23.45196149845568 }
]
}| Status | Opis |
|---|---|
200 | Successful response. |
400 | Invalid query parameters. |
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. |
503 | Service is warming up. |
Przeglądaj dane
Wyszukiwarka /szukaj to ta sama machina dla ludzi — spróbuj zanim podłączysz API:
Wszystkie endpointy /v1 zwracają JSON, obsługują CORS i są objęte dokumentem openapi.json. Interaktywna wersja tej referencji: /docs.
Limity: 60 zapytań/min na IP bez klucza; klucz API (nagłówek X-API-Key) dostaje własny kubełek. Po przekroczeniu endpointy odpowiadają HTTP 429 z nagłówkiem Retry-After. Szczegóły: limity i klucze · zasady użycia.
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.