Streets API (ULIC)
Name search across the whole country (q= without city) or within one locality (city=SYM). The query is diacritics-insensitive and matches either member order ('10 Marca' finds 'ul. 10 Marca'); sort=prominence ranks by PRG address points.
The /v1/streets/{symUl} detail aggregates every occurrence of the street — SYM_UL ids are unique per county only, so the same registration across dozens of localities comes back as one record with the full list. Each occurrence carries the hierarchy, population and PRG aggregates.
GET /v1/streets
With city it searches one locality; without it (with q) — the country-wide catalog with locality context on every row.
Try it live: /v1/streets?city=0983988&q=marsza
| Name | Required | Description |
|---|---|---|
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. |
Example
Streets of one locality
curl "https://teryt24.pl/v1/streets?city=0983988&q=marsza"Response:
{
"streets": [ { "name": "ul. Marszałkowska", "cecha": "ul.", "id": "12400", "city": "0983988" } ]
}| Status | Description |
|---|---|
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}
Occurrences cap at 100 (occurrenceCount/occurrencesTruncated); prg is null without the PRG dataset.
Try it live: /v1/streets/12400
| Name | Required | Description |
|---|---|---|
symUl path | ✓ | Street SYM_UL (5 digits, as returned by /v1/streets). |
Example
Every locality with ul. Marszałkowska
curl "https://teryt24.pl/v1/streets/12400"Response (truncated — first rows shown):
{
"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 | Description |
|---|---|
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). |
Browse the data
Every street has an info page with its occurrences and PRG data:
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.