{"openapi":"3.1.0","info":{"title":"Orbispect address search and verification API (GEO-01)","version":"1","summary":"Address autocomplete, geocoding with a confidence verdict, and reverse geocoding for Poland.","description":"Finds, checks and corrects addresses in Poland (about 8.6 million address points) and returns coordinates, postal code, municipality, county (powiat), voivodeship and TERYT codes. Tolerates typos, missing Polish diacritics, reversed word order and abbreviations. Every answer carries a status and a confidence (0 to 1). Also finds road and rail kilometre markers, railway stations, schools and fuel stations by name. Free to try without a key, with usage limits per IP address (HTTP 429 when exceeded); queries are not stored. Optional location-aware ranking: results near the end user can be shown first, either by passing lat and lon (with bias gps, adres or ip) or by the server-side option that uses the approximate location of the caller's IP address when no point is passed (on by default in this deployment; used on the fly, never stored or returned). Field names in responses are Polish. Show the `atrybucja` field when presenting data to a person.","contact":{"name":"Orbispect","url":"https://orbispect.com/contact"}},"servers":[{"url":"https://orbispect.com/geo-01","description":"Production"}],"tags":[{"name":"Search","description":"Autocomplete and geocoding"},{"name":"Reverse","description":"Coordinates to address"},{"name":"Meta","description":"Data version and limits"}],"paths":{"/v1/autocomplete":{"get":{"tags":["Search"],"operationId":"autocomplete","summary":"Address suggestions as you type","description":"Up to 10 suggestions for a partial or misspelled query; the last word may be unfinished. Location-aware ranking is optional: pass lat and lon (and bias) to put results nearest the end user first. Without lat/lon the service can use the approximate location of the caller's IP address instead (server option, on by default in this deployment; used on the fly, never stored or returned). It suits calls made from the end user's browser, for example a checkout form.","parameters":[{"$ref":"#/components/parameters/q"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":10,"default":6},"description":"Number of suggestions."},{"$ref":"#/components/parameters/lat"},{"$ref":"#/components/parameters/lon"},{"$ref":"#/components/parameters/bias"},{"$ref":"#/components/parameters/teryt"}],"responses":{"200":{"description":"Suggestions, best first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"},"example":{"zapytanie":"Armii Krajowej 5 Otwo","wyniki":[{"typ":"adres","etykieta":"Armii Krajowej 5, 05-400 Otwock","opis":"mazowieckie","ulica":"Armii Krajowej","numer":"5","kod_pocztowy":"05-400","miejscowosc":"Otwock","gmina":"Otwock","powiat":"otwocki","wojewodztwo":"mazowieckie","teryt_gmina":"1417021","teryt_powiat":"1417","lat":52.104012,"lon":21.268326,"dopasowanie":"prefiks","pewnosc":1,"status":"prawdopodobny"}],"poprawki":[],"bias":null,"wersja_danych":"2026-10-01"}}}},"400":{"$ref":"#/components/responses/Blad"},"429":{"$ref":"#/components/responses/Limit"}}}},"/v1/geocode":{"get":{"tags":["Search"],"operationId":"geocode","summary":"Verified address: best match with status and confidence","description":"Returns one best address (or place, or kilometre marker) with a status, a confidence, components, the corrections made and alternatives. Accepts free text such as 'Warszwska 9 Otwok', 'lodz piotrkowska 100', 'Dziecinów 3A', 'Warszawska 9 05-400', 'DK50 km 172,3'.","parameters":[{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/lat"},{"$ref":"#/components/parameters/lon"},{"$ref":"#/components/parameters/bias"},{"$ref":"#/components/parameters/teryt"}],"responses":{"200":{"description":"Verdict and best match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeocodeResponse"},"example":{"status":"prawdopodobny","pewnosc":0.85,"jednoznaczny":true,"adres":{"typ":"adres","etykieta":"Warszawska 9, 05-400 Otwock","opis":"mazowieckie","ulica":"Warszawska","numer":"9","kod_pocztowy":"05-400","miejscowosc":"Otwock","gmina":"Otwock","powiat":"otwocki","wojewodztwo":"mazowieckie","teryt_gmina":"1417021","teryt_powiat":"1417","id_prg":"d6d0fc39-1c75-4110-bcbc-9069dd351c55","lat":52.111434,"lon":21.262115,"dopasowanie":"literowka","pewnosc":0.89},"alternatywy":[],"poprawki":[{"z":"warszwska","na":["warszawska","warszewska"]},{"z":"otwok","na":["otwock","otok"]}],"wersja_danych":"2026-10-01"}}}},"400":{"$ref":"#/components/responses/Blad"},"429":{"$ref":"#/components/responses/Limit"}}}},"/v1/reverse":{"get":{"tags":["Reverse"],"operationId":"reverse","summary":"Nearest address to coordinates","description":"The nearest registered address to a WGS84 point in Poland, its distance in metres and optional neighbours. `wynik` is null when there is no address within the radius (for example in a forest); a point outside Poland returns a `uwaga`.","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"Latitude, WGS84."},{"name":"lon","in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180},"description":"Longitude, WGS84."},{"name":"promien","in":"query","schema":{"type":"integer","minimum":20,"maximum":1000,"default":300},"description":"Search radius in metres."},{"name":"sasiedzi","in":"query","schema":{"type":"integer","minimum":0,"maximum":5,"default":0},"description":"Number of additional nearest addresses."}],"responses":{"200":{"description":"Nearest address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReverseResponse"}}}},"400":{"$ref":"#/components/responses/Blad"},"429":{"$ref":"#/components/responses/Limit"}}}},"/v1/info":{"get":{"tags":["Meta"],"operationId":"info","summary":"Data version, number of address points and usage limits","responses":{"200":{"description":"Service information.","content":{"application/json":{"schema":{"type":"object","properties":{"usluga":{"type":"string"},"wersja_danych":{"type":"string"},"punkty_adresowe":{"type":"integer"},"dokumenty":{"type":"integer"},"limity":{"type":"object"},"atrybucja":{"type":"string"}}}}}}}}}},"components":{"parameters":{"q":{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":200},"description":"Free-text address, place or kilometre marker, in Polish. Polish diacritics are optional; up to two typos per word are tolerated.","example":"Warszwska 9 Otwok"},"lat":{"name":"lat","in":"query","schema":{"type":"number","minimum":48,"maximum":55.5},"description":"Optional reference latitude (WGS84) used only to rank results nearest first; not a filter. Give together with lon."},"lon":{"name":"lon","in":"query","schema":{"type":"number","minimum":13.5,"maximum":24.5},"description":"Optional reference longitude (WGS84)."},"bias":{"name":"bias","in":"query","schema":{"type":"string","enum":["gps","adres","ip"],"default":"gps"},"description":"Source of the reference point: gps (exact, default), adres (a chosen address) or ip (approximate, wider window). Location-aware ranking is optional; without lat and lon the service may use the approximate location of the caller's IP address (server option, never stored or returned)."},"teryt":{"name":"teryt","in":"query","schema":{"type":"string","pattern":"^\\d{2}(\\d{2}(\\d{2}\\d?)?)?$"},"description":"Filter by TERYT prefix of 2, 4, 6 or 7 digits (voivodeship, county, municipality)."}},"responses":{"Blad":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Blad"}}}},"Limit":{"description":"Usage limit exceeded for this IP address (per minute or per day). Retry after the time given in the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Blad"}}}}},"schemas":{"Blad":{"type":"object","properties":{"blad":{"type":"object","properties":{"kod":{"type":"string"},"opis":{"type":"string"}}}}},"Wynik":{"type":"object","description":"One result: an address, street, town, kilometre marker or named place.","properties":{"typ":{"type":"string","enum":["adres","ulica","miejscowosc","pikietaz","stacja_kolejowa","szkola","stacja_paliw"],"description":"Kind of result."},"etykieta":{"type":"string","description":"Ready-to-display line, for example 'Warszawska 10, 05-400 Otwock'."},"opis":{"type":"string","description":"Second line, for example the municipality and voivodeship."},"ulica":{"type":["string","null"]},"numer":{"type":["string","null"]},"kod_pocztowy":{"type":["string","null"]},"miejscowosc":{"type":["string","null"]},"gmina":{"type":["string","null"]},"powiat":{"type":["string","null"],"description":"County (powiat) name from TERYT, for example 'otwocki'; for a city with county rights the city name, for example 'Warszawa'. Derived from teryt_gmina (the first four digits)."},"wojewodztwo":{"type":["string","null"]},"teryt_gmina":{"type":"string","description":"TERYT code of the municipality (7 digits)."},"teryt_powiat":{"type":"string","description":"TERYT code of the county (4 digits, the first four digits of teryt_gmina). County names are not unique across voivodeships, so use the code to tell them apart."},"id_prg":{"type":["string","null"],"description":"Identifier of the address point; filled by geocode and reverse."},"lat":{"type":"number"},"lon":{"type":"number"},"dopasowanie":{"type":"string","enum":["dokladne","prefiks","literowka","czesciowe"],"description":"How the query matched: exact, unfinished last word, typo corrected, or only part of the query."},"pewnosc":{"type":"number","minimum":0,"maximum":1,"description":"Confidence of the match (not a probability). For kilometre markers it expresses how the position was derived: 0.95 a marker post at that kilometre, 0.85 interpolated between posts."},"status":{"type":"string","enum":["potwierdzony","prawdopodobny","numer_nieznaleziony","czesciowy"]},"uwaga":{"type":"string","description":"Note, for example that a kilometre-marker position is approximate."},"odleglosc_m":{"type":"number","description":"Reverse geocoding only: distance from the requested point."}},"required":["typ","etykieta","lat","lon"]},"Poprawka":{"type":"object","properties":{"z":{"type":"string","description":"Word as typed."},"na":{"type":"array","items":{"type":"string"},"description":"Candidate corrections, best first."}}},"AutocompleteResponse":{"type":"object","properties":{"zapytanie":{"type":"string"},"wyniki":{"type":"array","items":{"$ref":"#/components/schemas/Wynik"}},"poprawki":{"type":"array","items":{"$ref":"#/components/schemas/Poprawka"}},"bias":{"type":["string","null"],"enum":["gps","adres","ip",null],"description":"Where the reference point came from, or null when none was used."},"wersja_danych":{"type":"string"},"atrybucja":{"type":"string","description":"Attribution text to show when presenting data."}}},"GeocodeResponse":{"type":"object","properties":{"status":{"type":"string","enum":["potwierdzony","prawdopodobny","numer_nieznaleziony","czesciowy","nie_znaleziono"],"description":"confirmed (exactly one matching address, no corrections), likely (exists, but corrected, completed or ambiguous), number not found (street exists, number does not), partial (only part of the query matched), not found."},"pewnosc":{"type":"number","minimum":0,"maximum":1},"jednoznaczny":{"type":"boolean"},"adres":{"oneOf":[{"$ref":"#/components/schemas/Wynik"},{"type":"null"}]},"alternatywy":{"type":"array","items":{"$ref":"#/components/schemas/Wynik"}},"poprawki":{"type":"array","items":{"$ref":"#/components/schemas/Poprawka"}},"wersja_danych":{"type":"string"},"atrybucja":{"type":"string"}},"required":["status"]},"ReverseResponse":{"type":"object","properties":{"wynik":{"oneOf":[{"$ref":"#/components/schemas/Wynik"},{"type":"null"}]},"sasiedzi":{"type":"array","items":{"$ref":"#/components/schemas/Wynik"}},"promien_m":{"type":"integer"},"uwaga":{"type":"string"},"wersja_danych":{"type":"string"},"atrybucja":{"type":"string"}}}}}}