Ulice w API (ULIC)
Wyszukiwanie po nazwie w całym kraju (q= bez city) albo w obrębie jednej miejscowości (city=SYM). Zapytanie jest niewrażliwe na diakrytyki i dopasowuje naturalną kolejność członów („10 Marca” znajduje „ul. 10 Marca”), a sort=prominence rankinguje wg punktów adresowych PRG.
Karta /v1/streets/{symUl} agreguje wszystkie wystąpienia ulicy — identyfikatory SYM_UL są unikatowe tylko w obrębie powiatu, więc ta sama rejestracja w dziesiątkach miejscowości wraca jako jeden rekord z pełną listą. Każde wystąpienie niesie hierarchię, ludność i agregaty PRG.
GET /v1/streets
Z city szuka w jednej miejscowości; bez city (z q) — katalog krajowy z kontekstem miejscowości w każdym wierszu.
Sprawdź na żywo: /v1/streets?city=0983988&q=marsza
| Nazwa | Wymagany | Opis |
|---|---|---|
city | — | Locality SYM (7 digits, as returned by /v1/localities). Optional: omit it (with q) for a country-wide street search. |
q | — | Diacritics-insensitive prefix against the street name without its 'ul.' prefix, in either member order — the natural reading order ('10 Marca' finds 'ul. 10 Marca') or the register-order main member ('korfantego' finds 'ul. Wojciecha Korfantego'). Required (and triggers country-wide search) when city is absent; optional within a city (omitted → first `limit` streets alphabetically). |
limit | — | Maximum results per page (1–50). |
offset | — | Skip the first N results (0-based, max 10000) to page past the limit. |
sort | — | 'name' (default) keeps the established search-key ordering; 'prominence' ranks by real-world volume — PRG address points on the street first, then how many localities register it (ULIC), then the name key as the tie-break. The response carries addressCount/localityCount in this mode. |
Przykład
Ulice jednej miejscowości
curl "https://teryt24.pl/v1/streets?city=0983988&q=marsza"Odpowiedź:
{
"streets": [ { "name": "ul. Marszałkowska", "cecha": "ul.", "id": "12400", "city": "0983988" } ]
}| Status | Opis |
|---|---|
200 | Successful response. |
400 | Invalid query parameters. |
404 | Unknown locality SYM. |
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. |
500 | Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic — error detail lives in the server logs, never in the response. |
503 | Street dataset not available (fetch it via POST /admin/fetch-data?datasets=ulic). |
GET /v1/streets/{symUl}
Wystąpienia są ograniczone do 100 (occurrenceCount/occurrencesTruncated), prg jest null bez zbioru PRG.
Sprawdź na żywo: /v1/streets/12400
| Nazwa | Wymagany | Opis |
|---|---|---|
symUl path | ✓ | Street SYM_UL (5 digits, as returned by /v1/streets). |
Przykład
Wszystkie miejscowości z ul. Marszałkowska
curl "https://teryt24.pl/v1/streets/12400"Odpowiedź (skrócona — pokazano pierwsze wiersze):
{
"street": { "id": "12400", "cecha": "ul.", "name": "ul. Marszałkowska" },
"occurrenceCount": 27,
"occurrences": [
{ "sym": "0983988", "localityName": "Dzierżoniów", "province": "DOLNOŚLĄSKIE", "county": "dzierżoniowski", "municipality": "Dzierżoniów", "citySlug": "dzierzoniow", "rm": "96", "population": 31866, "lat": 50.72749999878521, "lon": 16.651111042500133, "prg": { "addressCount": 14, "postalCodes": ["58-200"], "centroidLat": 50.73218658896927, "centroidLon": 16.64026733421228, "houseNumbers": ["1", "10", "11", "12"] } }
]
}| Status | Opis |
|---|---|
200 | Successful response. |
400 | Invalid query parameters. |
404 | Unknown street SYM_UL. |
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. |
500 | Unexpected server failure (e.g. the database is unreachable). The body is deliberately generic — error detail lives in the server logs, never in the response. |
503 | Street dataset not available (fetch it via POST /admin/fetch-data?datasets=ulic). |
Przeglądaj dane
Każda ulica ma stronę informacyjną z wystąpieniami i danymi PRG:
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.