Polish address data in one REST API
Cities, localities, streets, postal codes and address validation — straight from the GUS TERYT, ULIC and PRG registers. One HTTP query, a JSON answer, ready to wire into forms and maps.
What is in the API
All endpoints return JSON, speak CORS, and share one OpenAPI-documented surface. Responses carry official registry identifiers (SYM, TERC codes) — the descriptions below are the only translated part.
City autocomplete
Tolerant of typos (bigram Dice), WGS84 coordinates, autocomplete / resolve / hybrid modes.
/v1/cities?q=warsz&limit=5
Every locality
Each self-standing SIMC locality — villages, settlements, hamlets — with kind (RM) and TERC hierarchy filters, a geographic mode, pagination and a detail card.
/v1/localities?q=kolonia&lat=52.2&lon=21.0
Administrative hierarchy
Voivodeships → counties → municipalities (TERC) — ideal for cascading address selects.
/v1/regions/14/counties
Streets within a locality
Search a street within one locality (SYM) from the ULIC register — over 310k entries.
/v1/streets?city=0983988&q=marsza
Postal codes
Postal code → locality (PNA, with coordinates) or the reverse: the code list on a locality's /v1/localities/:sym card.
/v1/postal-codes?q=00-002
Address validation
House-number verification against the PRG register — locality symbol + number (street optional).
/v1/geocode?sym=0988796&number=16
Reverse geocoding
Nearest localities for coordinates, with distance in kilometres — for maps and GPS.
/v1/reverse-geocode?lat=52.23&lon=21.01
Caching and ETags built in
Successful GET responses are cacheable (Cache-Control: 1 day) and versioned with an ETag — a 304 saves the transfer.
ETag + If-None-Match
Browsable pages
An information page per locality and postal code (in Polish) — e.g. Warszawa, Śródmieście or code 00-002.
/miasta/warszawa
Quick start
No keys, no sign-up — first query in 10 seconds.
curl "https://teryt24.pl/v1/cities?q=warsz&limit=5"
curl "https://teryt24.pl/v1/geocode?sym=0988796&streetName=Świętokrzyska&number=16"
curl "https://teryt24.pl/v1/reverse-geocode?lat=52.2297&lon=21.0122&limit=3"
Full parameters and response schemas in the API reference
and the machine-readable openapi.json. Limits: 60 requests/min per IP;
beyond that, HTTP 429 with a Retry-After header. What the server
sees about your requests: /v1/whoami.