{"openapi":"3.1.0","info":{"title":"Addresses Public API","version":"1.0.0","description":"Polish address autocomplete, postal code lookup, and TERYT hierarchy. Subscribe on RapidAPI and call endpoints with `X-RapidAPI-Key` and `X-RapidAPI-Host`. Direct access to the origin server is blocked in production."},"servers":[{"url":"https://api.addresses-lookup.grynienko.com","description":"Current server"}],"tags":[{"name":"Health","description":"Unauthenticated health check"},{"name":"Autocomplete","description":"Typeahead for forms"},{"name":"Postal","description":"Postal code lookup by code or city"},{"name":"Resolve","description":"Full address resolution"},{"name":"Regions","description":"Cascading region picker. Drill down with nested URLs; use each item's `id` (and commune `typeId`) as the next path segment. Locality `id` is the GUS SIMC code (same as `/addresses/resolve?sym=`)."}],"components":{"securitySchemes":{"RapidAPIKey":{"type":"apiKey","in":"header","name":"X-RapidAPI-Key","description":"API key from your RapidAPI dashboard (Apps → Default Application → API Key)"}},"schemas":{"ErrorBody":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["FORBIDDEN","VALIDATION_ERROR","NOT_FOUND","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}},"Health":{"type":"object","properties":{"status":{"type":"string","example":"ok"}}},"ListMeta":{"type":"object","properties":{"count":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"}}},"AutocompleteLocality":{"type":"object","required":["type","label","province","county","commune","locality","postalCodes"],"properties":{"type":{"type":"string","const":"locality"},"label":{"type":"string","example":"Wrocław, DOLNOŚLĄSKIE"},"province":{"type":"string","example":"DOLNOŚLĄSKIE"},"county":{"type":"string","example":"Wrocław"},"commune":{"type":"string","example":"Wrocław"},"locality":{"type":"string","example":"Wrocław"},"postalCodes":{"type":"array","items":{"type":"string"},"example":["50-001","50-002"]}}},"AutocompleteStreet":{"type":"object","required":["type","label","province","county","commune","locality","street","postalCodes"],"properties":{"type":{"type":"string","const":"street"},"label":{"type":"string","example":"ul. Grodzka, Wrocław"},"province":{"type":"string","example":"DOLNOŚLĄSKIE"},"county":{"type":"string","example":"Wrocław"},"commune":{"type":"string","example":"Wrocław"},"communeKind":{"type":"string","example":"gmina miejska"},"locality":{"type":"string","example":"Wrocław"},"street":{"type":"string","example":"ul. Grodzka"},"postalCodes":{"type":"array","items":{"type":"string"},"example":["50-001"]}}},"AutocompletePostalCode":{"type":"object","required":["type","postalCode","label"],"properties":{"type":{"type":"string","const":"postalCode"},"postalCode":{"type":"string","example":"50-001"},"label":{"type":"string","example":"50-001"}}},"AutocompleteItem":{"oneOf":[{"$ref":"#/components/schemas/AutocompleteLocality"},{"$ref":"#/components/schemas/AutocompleteStreet"},{"$ref":"#/components/schemas/AutocompletePostalCode"}]},"AutocompleteListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AutocompleteItem"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}},"PostalAssignment":{"type":"object","required":["postalCode","locality","commune","county","province"],"properties":{"postalCode":{"type":"string","example":"50-001"},"locality":{"type":"string","example":"Wrocław"},"street":{"type":"string","example":"ul. Grodzka"},"district":{"type":"string","example":"Oporów"},"commune":{"type":"string","example":"Wrocław"},"county":{"type":"string","example":"Wrocław"},"province":{"type":"string","example":"DOLNOŚLĄSKIE"},"numbering":{"type":"string","example":"1-999 nieparzyste"}}},"PostalListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PostalAssignment"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}},"ResolvedAddress":{"type":"object","required":["province","county","commune","locality","postalCodes"],"properties":{"province":{"type":"string","example":"DOLNOŚLĄSKIE"},"county":{"type":"string","example":"Wrocław"},"commune":{"type":"string","example":"Wrocław"},"communeKind":{"type":"string","example":"gmina miejska"},"locality":{"type":"string","example":"Wrocław"},"street":{"type":"string","example":"ul. Grodzka"},"postalCodes":{"type":"array","items":{"type":"string"},"example":["50-001"]}}},"ResolvedResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ResolvedAddress"}}},"RegionPickerItem":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","description":"Path segment for the next level (`woj`, `pow`, or SIMC locality id).","example":"02"},"name":{"type":"string","example":"Dolnośląskie"}}},"CommunePickerItem":{"type":"object","required":["id","typeId","name"],"properties":{"id":{"type":"string","description":"GMI segment; use as `{gmi}` in `/communes/{gmi}/kind/{rodz}/localities`.","example":"03"},"typeId":{"type":"string","description":"TERYT RODZ segment; use as `{rodz}` in the localities path.","example":"9"},"name":{"type":"string","example":"Wrocław-Krzyki"},"communeKind":{"type":"string","description":"Human-readable gmina type (from GUS NAZWA_DOD).","example":"delegatura"}}},"LocalityPickerItem":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","description":"GUS SIMC identifier (7 digits); same value as `sym` in resolve endpoints.","example":"0986544"},"name":{"type":"string","example":"Wrocław"}}},"DistrictPickerItem":{"type":"object","required":["name","aliases"],"properties":{"name":{"type":"string","example":"Oporów"},"aliases":{"type":"array","items":{"type":"string"},"example":["OPOROW"]}}},"StreetItem":{"type":"object","required":["name","postalCodes"],"properties":{"name":{"type":"string","example":"ul. Grodzka"},"postalCodes":{"type":"array","items":{"type":"string"},"example":["50-001"]}}},"RegionPickerListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RegionPickerItem"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}},"CommunePickerListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommunePickerItem"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}},"LocalityPickerListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LocalityPickerItem"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}},"DistrictPickerListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DistrictPickerItem"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}},"StreetListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StreetItem"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}}},"responses":{"Forbidden":{"description":"Direct access to origin without RapidAPI proxy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"examples":{"default":{"value":{"error":{"code":"FORBIDDEN","message":"Direct access not allowed"}}}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"examples":{"default":{"value":{"error":{"code":"NOT_FOUND","message":"Postal code not found"}}}}}}}}},"paths":{"/health":{"get":{"tags":["Health"],"security":[],"summary":"Health check","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"},"examples":{"default":{"value":{"status":"ok"}}}}}}}}},"/v1/autocomplete/localities":{"get":{"tags":["Autocomplete"],"summary":"Autocomplete localities","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"example":"wroc"},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}},{"name":"province","in":"query","schema":{"type":"string"},"description":"Województwo TERYT code (e.g. 02)"}],"responses":{"200":{"description":"Locality suggestions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteListResponse"},"examples":{"default":{"value":{"data":[{"type":"locality","label":"Wrocław, DOLNOŚLĄSKIE","province":"DOLNOŚLĄSKIE","county":"Wrocław","commune":"Wrocław","locality":"Wrocław","postalCodes":["50-001","50-002"]}],"meta":{"count":1,"limit":10}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/autocomplete/streets":{"get":{"tags":["Autocomplete"],"summary":"Autocomplete streets","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"example":"grod"},{"name":"locality","in":"query","schema":{"type":"string"},"description":"SIMC sym to scope search to one locality","example":"0986283"},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Street suggestions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteListResponse"},"examples":{"default":{"value":{"data":[{"type":"street","label":"ul. Grodzka, Wrocław","province":"DOLNOŚLĄSKIE","county":"Wrocław","commune":"Wrocław","communeKind":"gmina miejska","locality":"Wrocław","street":"ul. Grodzka","postalCodes":["50-001"]}],"meta":{"count":1,"limit":10}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/autocomplete/postal-codes":{"get":{"tags":["Autocomplete"],"summary":"Autocomplete postal codes","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"example":"50-0"},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Postal code suggestions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteListResponse"},"examples":{"default":{"value":{"data":[{"type":"postalCode","postalCode":"50-001","label":"50-001"}],"meta":{"count":1,"limit":10}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/autocomplete/unified":{"get":{"tags":["Autocomplete"],"summary":"Unified autocomplete (localities + streets)","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"example":"wroc"},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"Mixed locality and street suggestions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteListResponse"},"examples":{"default":{"value":{"data":[{"type":"locality","label":"Wrocław, DOLNOŚLĄSKIE","province":"DOLNOŚLĄSKIE","county":"Wrocław","commune":"Wrocław","locality":"Wrocław","postalCodes":["50-001"]},{"type":"street","label":"ul. Wrocławska, Legnica","province":"DOLNOŚLĄSKIE","county":"legnicki","commune":"Legnica","communeKind":"gmina miejska","locality":"Legnica","street":"ul. Wrocławska","postalCodes":["59-220"]}],"meta":{"count":2,"limit":10}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/postal-codes/{code}":{"get":{"tags":["Postal"],"summary":"Lookup by postal code","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"example":"00-001"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}}],"responses":{"200":{"description":"Postal code assignments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostalListResponse"},"examples":{"default":{"value":{"data":[{"postalCode":"00-001","locality":"Warszawa","street":"ul. Senatorska","commune":"Warszawa","county":"Warszawa","province":"MAZOWIECKIE"}],"meta":{"count":1,"limit":50,"total":1}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/cities/{city}/postal-codes":{"get":{"tags":["Postal"],"summary":"Postal codes for a city","parameters":[{"name":"city","in":"path","required":true,"schema":{"type":"string"},"example":"Wrocław"}],"responses":{"200":{"description":"Postal codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostalListResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/cities/{city}/districts/{district}/postal-codes":{"get":{"tags":["Postal"],"summary":"Postal codes for a city district","parameters":[{"name":"city","in":"path","required":true,"schema":{"type":"string"},"example":"Wrocław"},{"name":"district","in":"path","required":true,"schema":{"type":"string"},"example":"Oporów"}],"responses":{"200":{"description":"Postal codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostalListResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/cities/{city}/streets/{street}/postal-codes":{"get":{"tags":["Postal"],"summary":"Postal codes for a street in a city","parameters":[{"name":"city","in":"path","required":true,"schema":{"type":"string"},"example":"Wrocław"},{"name":"street","in":"path","required":true,"schema":{"type":"string"},"example":"ul. Grodzka"}],"responses":{"200":{"description":"Postal codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostalListResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/addresses/resolve":{"get":{"tags":["Resolve"],"summary":"Resolve address by SIMC sym and optional SYM_UL","parameters":[{"name":"sym","in":"query","required":true,"schema":{"type":"string"},"description":"SIMC locality identifier","example":"0986283"},{"name":"symUl","in":"query","schema":{"type":"string"},"description":"Street SYM_UL when resolving to street level","example":"12345"}],"responses":{"200":{"description":"Resolved address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolvedResponse"},"examples":{"default":{"value":{"data":{"province":"DOLNOŚLĄSKIE","county":"Wrocław","commune":"Wrocław","communeKind":"gmina miejska","locality":"Wrocław","street":"ul. Grodzka","postalCodes":["50-001"]}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/addresses/resolve-by-path":{"get":{"tags":["Resolve"],"summary":"Resolve by TERYT label path","parameters":[{"name":"province","in":"query","required":true,"schema":{"type":"string"},"example":"DOLNOŚLĄSKIE"},{"name":"county","in":"query","required":true,"schema":{"type":"string"},"example":"Wrocław"},{"name":"commune","in":"query","required":true,"schema":{"type":"string"},"example":"Wrocław"},{"name":"locality","in":"query","required":true,"schema":{"type":"string"},"example":"Wrocław"},{"name":"street","in":"query","required":true,"schema":{"type":"string"},"example":"ul. Grodzka"}],"responses":{"200":{"description":"Resolved address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolvedResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/regions/provinces":{"get":{"tags":["Regions"],"summary":"List provinces","responses":{"200":{"description":"Provinces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionPickerListResponse"},"examples":{"default":{"value":{"data":[{"id":"02","name":"Dolnośląskie"}],"meta":{"count":1}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/regions/provinces/{woj}/counties":{"get":{"tags":["Regions"],"summary":"Counties in province","parameters":[{"name":"woj","in":"path","required":true,"description":"Province `id` from the provinces list (WOJ code).","schema":{"type":"string"},"example":"02"}],"responses":{"200":{"description":"Counties","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionPickerListResponse"},"examples":{"default":{"value":{"data":[{"id":"64","name":"Wrocław"}],"meta":{"count":1}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/regions/provinces/{woj}/counties/{pow}/communes":{"get":{"tags":["Regions"],"summary":"Communes in county","parameters":[{"name":"woj","in":"path","required":true,"description":"Province `id` from the provinces list.","schema":{"type":"string"},"example":"02"},{"name":"pow","in":"path","required":true,"description":"County `id` from the counties list (POW segment only, e.g. `19` — not WOJ+POW like `0219`).","schema":{"type":"string"},"example":"64"}],"responses":{"200":{"description":"Communes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunePickerListResponse"},"examples":{"default":{"value":{"data":[{"id":"03","typeId":"9","name":"Wrocław-Krzyki","communeKind":"delegatura"}],"meta":{"count":1}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/regions/provinces/{woj}/counties/{pow}/communes/{gmi}/kind/{rodz}/localities":{"get":{"tags":["Regions"],"summary":"Localities in commune","parameters":[{"name":"woj","in":"path","required":true,"schema":{"type":"string"},"example":"02"},{"name":"pow","in":"path","required":true,"schema":{"type":"string"},"example":"64"},{"name":"gmi","in":"path","required":true,"description":"Commune `id` from the communes list (GMI segment).","schema":{"type":"string"},"example":"03"},{"name":"rodz","in":"path","required":true,"description":"Commune `typeId` from the communes list (TERYT RODZ segment).","schema":{"type":"string"},"example":"9"}],"responses":{"200":{"description":"Localities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalityPickerListResponse"},"examples":{"default":{"value":{"data":[{"id":"0986544","name":"Wrocław"}],"meta":{"count":1}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/regions/localities/{id}/districts":{"get":{"tags":["Regions"],"summary":"Districts (dzielnice) for locality","parameters":[{"name":"id","in":"path","required":true,"description":"Locality `id` from the localities list (GUS SIMC, 7 digits).","schema":{"type":"string"},"example":"0986544"}],"responses":{"200":{"description":"Districts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DistrictPickerListResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/regions/localities/{id}/streets":{"get":{"tags":["Regions"],"summary":"Streets in locality","parameters":[{"name":"id","in":"path","required":true,"description":"Locality `id` from the localities list (GUS SIMC).","schema":{"type":"string"},"example":"0986544"},{"name":"q","in":"query","schema":{"type":"string"},"example":"grod"},{"name":"district","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":200}}],"responses":{"200":{"description":"Streets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StreetListResponse"},"examples":{"default":{"value":{"data":[{"name":"ul. Grodzka","postalCodes":["50-001"]}],"meta":{"count":1,"limit":100}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}