Bramka Nominatim 5.1 do wyszukiwania adresów i POI. Ta strona opisuje publiczne endpointy, token, limity i przepis na najbliższy obiekt — czego samo API nie sortuje po odległości.
Aktualizacja 14.11.2026 · wersja oprogramowania 5.1.0 · sublicencja „IMETROLL Laboratory of Technology”
Adres bazowy: https://geoloc.imetroll.com. Usługa udostępnia API zgodne z Nominatim 5.1: /search, /reverse, /lookup, /details i /status. Wyniki pochodzą z OpenStreetMap (ODbL). Domyślna bramka dla komponentu Delphi TNominatimSearchProvider i raportów Parcel.
Ta dokumentacja jest statyczna i nie zawiera prawdziwego tokenu. W przykładach jest wyłącznie placeholder YOUR_TOKEN.
Wszystkie metody to GET (ew. HEAD). Do każdego zapytania (także /status) należy dodać token=YOUR_TOKEN. Bez tokenu serwer odpowiada 401 z komunikatem w stylu „Brak tokena – dodaj &token=…”.
Wyszukiwanie tekstowe lub strukturalne. Kolejność wyników to ranking ważności Nominatim (importance), nie odległość. Duży viewbox przy małym limit może odrzucić obiekt faktycznie najbliższy.
| Parametr | Opis |
|---|---|
q | Zapytanie wolnotekstowe. Działa też wiele special phrases po polsku i operatory w stylu [railway=station] (patrz niżej). |
street, city, county, state, country, postalcode | Wyszukiwanie strukturalne (zamiast q). |
format | json (zalecane), także jsonv2, geojson, xml. |
limit | Liczba wyników. Do szukania „najbliższego” dawaj zapas (np. 20), nie 1. |
viewbox | lon1,lat1,lon2,lat2 (zachód, północ, wschód, południe albo para narożników). Preferowany obszar. |
bounded | 1 = tylko wewnątrz viewbox. |
countrycodes | np. pl. |
accept-language | np. pl. |
addressdetails, namedetails, extratags | Flagi Nominatim 0/1. extratags=1 jest przyjmowane, ale tagi nie wracają — styl importu bez extratags (patrz niżej). |
layer / featureType | Filtrowanie warstw Nominatim 5 (np. address, poi, railway) tam, gdzie serwer to obsługuje. |
dedupe, exclude_place_ids, polygon_geojson | Jak w Nominatim 5.1. |
token | Wymagany sekret. Nigdy nie wklejaj prawdziwego tokenu do dokumentacji, logów ani JS w przeglądarce publicznej. |
GET https://geoloc.imetroll.com/search?q=…&format=json&limit=20&namedetails=0&accept-language=pl&viewbox=W,N,E,S&bounded=1&countrycodes=pl&token=YOUR_TOKENAdres dla punktu lat, lon. Opcjonalnie zoom (poziom szczegółowości), format, addressdetails, accept-language, token.
GET https://geoloc.imetroll.com/reverse?lat=52.46412&lon=20.88074&format=json&zoom=18&accept-language=pl&token=YOUR_TOKENObiekty po identyfikatorach OSM: osm_ids=W123,R456,N789 (prefiks typu W/R/N), plus format, addressdetails, token.
Szczegóły jednego miejsca: place_id=… albo osmtype=W&osmid=…. Pozostałe opcje jak w Nominatim 5.1 DetailsOptions.
Sonda żywotności. Też wymaga tokenu (bez niego: HTTP 401). Przy poprawnym tokenie zwraca m.in. software_version (5.1.0) i sublicencję „IMETROLL Laboratory of Technology”. Wynik sondy warto cache’ować po stronie klienta (w komponencie Delphi: StatusCacheSeconds).
token=***), tak jak metoda RedactedURL w Delphi. Jeśli token jest powiązany z Referer/Origin, używaj wartości podanych przy wydaniu klucza.
401 (pekNoToken).403 (pekInvalidToken).MinRequestIntervalMs = 1000). Przy przekroczeniu spodziewaj się 429 i zastosuj przerwę (RateLimitBackoffMs). Kolejka zapytań jest lepsza niż równoległe „bursty”.404 zły adres, 502/503 serwer niedostępny, 504 timeout.Nie ma osobnego endpointu „daj najbliższy X”. /search sortuje po importance. Żeby dostać najbliższy POI (szkołę, stację PKP, sklep…):
viewbox wokół punktu i ustawiaj bounded=1.limit z zapasem (ok. 20). Mały limit + duży viewbox pomija bliskie, mniej „ważne” obiekty.[railway=station] i [railway=halt] (albo stacja kolejowa oraz przystanek kolejowy). Samo „stacja kolejowa” nie zwraca haltów (np. Chotomów).stacja kolejowa near Skrzeszew przy bounded=1 może zwrócić 0 wyników — „near” + bounded nie zastępuje warstw + haversine.W raportach Parcel ten przepis jest zaimplementowany w module family POI (lista wszystkich POI w 10 km, a gdy w 10 km nic nie ma — jeden najbliższy poza 10 km, do 50 km).
Na geoloc.imetroll.com special phrases są zaimportowane: działają polskie nazwy kategorii i operatory w nawiasach kwadratowych. Na lokalnym Nominatim 127.0.0.1:8110 (dane Polski) special phrases nie są zaimportowane — tam polegaj na tagach / Overpass.
| Kategoria PL | EN | Tagi OSM / class+type | Przykładowe q= (special phrases) |
|---|---|---|---|
| żłobek | nursery | amenity=childcare | żłobek, nursery |
| przedszkole | kindergarten | amenity=kindergarten | przedszkole, kindergarten |
| szkoła podstawowa | primary school | amenity=school + isced:level=1 / nazwa | szkoła podstawowa, szkoła |
| liceum/technikum | secondary school | amenity=school + liceum/technikum / isced 2–3 | liceum, technikum, szkoła średnia |
| sklep spożywczy | grocery | shop=convenience|greengrocer|butcher|deli|general|grocery|kiosk | sklep spożywczy, sklep |
| market | supermarket | shop=supermarket|hypermarket|wholesale | supermarket, Biedronka, Lidl, market |
| piekarnia | bakery | shop=bakery | piekarnia, bakery |
| apteka | pharmacy | amenity=pharmacy | apteka, pharmacy |
| poczta | post office | amenity=post_office | poczta, urząd pocztowy |
| Paczkomat/InPost | parcel locker | amenity=parcel_locker, brand=InPost | InPost, Paczkomat |
| stacja paliw | fuel station | amenity=fuel | Orlen, stacja paliw, Circle K, Shell, BP |
| przychodnia POZ | primary clinic | amenity=clinic / healthcare=clinic | przychodnia, ośrodek zdrowia, POZ |
| lekarz | doctor | amenity=doctors / healthcare=doctor | lekarz, gabinet lekarski |
| dentysta | dentist | amenity=dentist | dentysta, stomatolog |
| szpital/SOR | hospital / ER | amenity=hospital | szpital, SOR, hospital |
| boisko/Orlik | pitch / Orlik | leisure=pitch | Orlik, boisko |
| pływalnia | swimming pool | leisure=swimming_pool (pomiń access=private) | pływalnia, basen |
| hala sportowa | sports hall | leisure=sports_hall|sports_centre | hala sportowa |
| siłownia | gym | leisure=fitness_centre / amenity=gym | siłownia, fitness, gym |
| plac zabaw | playground | leisure=playground | plac zabaw, playground |
| park | park | leisure=park|garden | park, skwer |
| biblioteka | library | amenity=library | biblioteka, library |
| dom kultury | community centre | amenity=community_centre|arts_centre | dom kultury, GOK |
| kino | cinema | amenity=cinema | kino, cinema |
| kościół | church | amenity=place_of_worship | kościół, parafia, church |
| przystanek | bus stop | highway=bus_stop / amenity=bus_station | przystanek autobusowy, bus stop |
| stacja kolejowa / przystanek PKP | railway station / halt | railway=station oraz railway=halt | stacja kolejowa, przystanek kolejowy, [railway=station], [railway=halt] |
| OSP | fire station | amenity=fire_station | OSP, straż pożarna, remiza |
| policja | police | amenity=police (nie straż miejska) | policja, komisariat |
| bankomat | ATM | amenity=atm | bankomat, ATM |
Mapowanie musi brać pod uwagę tagi OSM, nie tylko nazwę (np. sklep to konkretne shop=*, nie każdy hit na słowo „sklep”). Halty kolejowe i stacje to dwie klasy.
extratags=1 nie zwraca słownika tagów OSM. Do tagów (isced:level, access, healthcare, brand, wikidata…) użyj Overpass. Preferowane publiczne instancje, w tej kolejności: https://overpass.openstreetmap.fr/api/interpreter, potem overpass-api.de, overpass.kumi.systems, overpass.private.coffee. Odpowiedź HTTP 200 z nie-datowym timestamp_osm_base (np. z overpass.osm.ch) należy odrzucić — to bywa pusta / zła baza, nie sukces.
Punkt testowy: działka przy ul. Familijnej 16a, Skrzeszew (gmina Wieliszew), centroid ok. lon=20.88074, lat=52.46412. Pomiary z 14.11.2026, token w URL zastąpiony placeholderem. Odległości liczone haversine od centroidu, nie „kolejnością z /search”.
GET https://geoloc.imetroll.com/search?q=przystanek+kolejowy&format=json&limit=20&namedetails=0&accept-language=pl&viewbox=20.75,52.56,21.01,52.37&bounded=1&countrycodes=pl&token=YOUR_TOKENWynik (skrót): halt Chotomów, ok. 5,4 km (5391 m). To samo daje q=[railway=halt]. Samo q=[railway=station] albo q=stacja kolejowa zwraca tylko stacje, bez haltów — Chotomowa wtedy nie ma.
GET https://geoloc.imetroll.com/search?q=stacja+kolejowa+near+Skrzeszew&format=json&bounded=1&viewbox=20.75,52.56,21.01,52.37&countrycodes=pl&token=YOUR_TOKENWynik: 0 trafień. Nie oznacza to braku stacji w okolicy. Użyj przepisu z warstw i haversine, osobno station + halt.
Gdyby brać tylko „stacja kolejowa”, lista pominęłaby Chotomów i inne halty.
Nazwy i odległości pochodzą z połączenia geoloc + lokalny Nominatim + Overpass; sam geoloc nie gwarantuje, że pierwszy element tablicy jest najbliższy.
| geoloc.imetroll.com | Lokalny Nominatim (127.0.0.1:8110) | |
|---|---|---|
| Oprogramowanie | Nominatim 5.1.0 (bramka) | Nominatim 5.1 (kontener mediagis, PBF Polski) |
| Special phrases | tak (nazwy PL i operatory) | nie |
| extratags | nie włączone | inny styl importu — i tak tagi do klasyfikacji bierz z Overpass, jeśli potrzeba pełnych tagów |
| Token | wymagany (YOUR_TOKEN) | usługa lokalna, bez publicznego tokenu |
| Zastosowanie | wspólna bramka (Parcel, komponenty Delphi, inne aplikacje) | uzupełnienie / fallback na serwerze aplikacji |
W praktyce dobre wyniki daje złożenie: najpierw geoloc (frazy), potem lokalny Nominatim, na końcu Overpass po tagach, z deduplikacją po współrzędnych i wyborem najbliższego.
Wikipedia i Wikidata nie są źródłem wyszukiwania najbliższego POI — nie zastąpią tagów OSM ani warstw odległości. Ewentualne uzupełnienie nazwy lub opisu ma sens tylko wtedy, gdy obiekt jest już znaleziony i ma z Overpassa tag wikidata / wikipedia. Nie dodawaj żywego API Wikipedii do ścieżki wyszukiwania.
Dane mapowe: © OpenStreetMap contributors, licencja ODbL. W aplikacji musi być widoczne zastrzeżenie „© OpenStreetMap contributors”. Nominatim jest oprogramowaniem open source; bramka geoloc.imetroll.com jest prowadzona przez IMETROLL Laboratory of Technology.
Publiczny nominatim.openstreetmap.org ma własne, ostrzejsze zasady (m.in. 1 zap/s, bez autouzupełniania) — ta dokumentacja dotyczy wyłącznie geoloc.imetroll.com.