Autocomplete — one query, the whole catalog
GET /v1/autosuggest merges four searches (cities, localities, streets, postal codes) into one suggestion list. The ranking is unified: the match tier (exact > prefix > alias > fuzzy) dominates, real-world prominence (population, address points) orders within a tier, and the optional lat/lon focus reorders by distance without restricting results.
Each layer reuses exactly the search its dedicated endpoint serves; a layer with a missing dataset contributes nothing and is named in layersDegraded. Response rows are a discriminated union on type, and label is the ready-to-display string.
GET /v1/autosuggest
layers= narrows the layers (city,locality,street,postal); limit 1–20, default 8.
Try it live: /v1/autosuggest?q=warsz&limit=6
| Name | Required | Description |
|---|---|---|
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). |
Example
All layers at once
curl "https://teryt24.pl/v1/autosuggest?q=warsz&limit=6"Response (truncated — first rows shown):
{
"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 | Description |
|---|---|
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. |
Browse the data
The /szukaj search page is the same machinery for humans — try it before wiring the API:
All /v1 endpoints return JSON, speak CORS and are covered by the openapi.json document. Interactive version of this reference: /en/docs.
Limits: 60 requests/min per IP without a key; an API key (the X-API-Key header) gets its own bucket. Over the limit the endpoints answer HTTP 429 with a Retry-After header. Details: limits & keys · usage policy.
Data: GUS TERYT, PRG address points (GUGiK), GeoNames postal codes — via teryt24.pl with a link to the usage policy. Server-side-only use is exempt.