TNominatimSearchProvider – Komponenty Delphi

Opis

Dostawca wyszukiwania dla wszystkich map. Obsługuje /search (wolny tekst i strukturalny), /reverse, /lookup, /details i /status. Przed zapytaniem sprawdza token i adres, sondą /status wykrywa niedziałający serwer, a limit zapytań pilnuje zasad użycia (1 zapytanie/s, obsługa HTTP 429).

Moduł: MapCommon.Search, MapCommon.Nominatim · Klasa bazowa: TMapSearchProvider (TComponent) · Platformy: VCL + FMX

TNominatimSearchProvider – podgląd poglądowy — Wyszukiwarka mapy z wynikami z TNominatimSearchProvider (odległość od markera głównego). *Podgląd poglądowy (nie zrzut z Delphi) – prawdziwa strona mapy komponentu w ramce imitującej formę.*

Demo na żywo

Wyszukiwanie wolne, strukturalne i odwrotne, /status, URL zapytania i czas odpowiedzi (limit 1/s).

▶ Otwórz demo HTML

Funkcje

Pełne parametry Nominatim 5.1: OutputFormat, Outputs (addressdetails, extratags, namedetails), Layers, FeatureType, ViewBox, Bounded, Dedupe, Polygon, ExcludePlaceIds, Email.
Walidacja przed wysłaniem: brak tokenu (pekNoToken), błędny adres (pekBadURL).
Sonda /status z pamięcią wyniku (CheckServerStatus, StatusCacheSeconds).
Klasyfikacja błędów TMapProviderErrorKind: 401 → pekNoToken, 403 → pekInvalidToken, 404 → pekBadURL, 429 → pekRateLimited, 502/503 → pekServerDown, 504 → pekTimeout.
Limit po stronie klienta: MinRequestIntervalMs = 1000 (kolejka, nic nie ginie) i przerwa RateLimitBackoffMs po 429.
Adresy per kontynent (ContinentBaseURLs) i automatyczne wykrywanie kontynentu.
Token nigdy nie trafia do DFM ani komunikatów błędów (maskowanie ***).

Licencja danych: wyniki pochodzą z OpenStreetMap (ODbL) – w aplikacji musi być widoczne „© OpenStreetMap contributors”. Publiczny serwer nominatim.openstreetmap.org ma własne zasady (1 zapytanie/s, bez autouzupełniania); domyślnie używana jest własna bramka geoloc.imetroll.com, a adres można zmienić bez aktualizacji programu.

Właściwości

Właściwość	Opis
BaseURL	Adres serwera; puste = `SearchProviderURL` mapy, potem bramka domyślna.
Token (public)	Sekret ustawiany w kodzie – nie zapisuje się w pliku formy.
TokenRequired, TokenFormat	Czy token jest wymagany, sposób przekazania.
Language, Limit, CountryCodes	Język wyników, liczba wyników, kraje.
OutputFormat, Outputs, Layers, FeatureType	Format i zakres danych.
ViewBox, Bounded, Dedupe, Polygon, PolygonThreshold	Obszar preferowany, deduplikacja, geometria.
DetailsOptions	Opcje zapytania /details.
Continent, ContinentFilter, SendContinentHint, ContinentBaseURLs	Wybór serwera według kontynentu.
CheckServerStatus, StatusCacheSeconds	Sonda /status i jej pamięć.
MinRequestIntervalMs, RateLimitBackoffMs	Limit zapytań (domyślnie 1000 ms) i przerwa po HTTP 429.
ConnectTimeout, Timeout, UserAgent	Limity czasu, identyfikacja aplikacji.

Zdarzenia

Zdarzenie	Opis
OnResults	Wyniki (rodzaj zapytania, tekst, `TMapGeoResults`, surowy JSON).
OnError	Błąd z rodzajem `pek*`, kodem HTTP i komunikatem PL/EN.
OnConnectionChecked	Wynik testu połączenia (/status).

Metody

Metoda	Opis
Search, SearchStructured, SearchInArea	Wyszukiwanie.
Reverse	Adres z punktu.
Lookup, Details, DetailsByPlaceId	Obiekty OSM.
CheckConnection, Status, InvalidateConnectionCache	Test połączenia.
Validate	Synchroniczna walidacja tokenu i adresu.
CancelPending, RedactedURL	Anulowanie, adres z ukrytym tokenem.

Przykłady

Konfiguracja i test połączenia

NominatimSearchProvider1.BaseURL := 'https://geoloc.imetroll.com';
NominatimSearchProvider1.Token := GetEnvironmentVariable('MAP_SEARCH_TOKEN');
NominatimSearchProvider1.Language := 'pl';
NominatimSearchProvider1.CountryCodes := 'pl';
NominatimSearchProvider1.MinRequestIntervalMs := 1000;   // maks. 1 zapytanie/s

// test połączenia: token, adres, /status
NominatimSearchProvider1.CheckConnection(
  procedure(Ok: Boolean; ErrorKind: TMapProviderErrorKind;
    const ErrorMessage, StatusJSON: string)
  begin
    if not Ok then
      ShowMessage(ErrorMessage);   // np. pekInvalidToken: "Token odrzucony (403)"
  end);

// wyszukiwanie strukturalne i obiekty OSM
NominatimSearchProvider1.SearchStructured('Marszałkowska 10', 'Warszawa', '00-001', 'pl');
NominatimSearchProvider1.Lookup('N240109189,W50637691');
NominatimSearchProvider1.Reverse(52.2297, 21.0122);

Obsługa błędów

procedure TForm1.NominatimSearchProvider1Error(Sender: TObject; Kind: TMapSearchKind;
  ErrorKind: TMapProviderErrorKind; const Query: string; StatusCode: Integer;
  const ErrorMessage, Sublicence: string);
begin
  case ErrorKind of
    pekNoToken, pekInvalidToken: ShowMessage('Sprawdź token: ' + ErrorMessage);
    pekRateLimited: StatusBar1.SimpleText := 'Za dużo zapytań – kolejne za chwilę';
    pekServerDown, pekTimeout:   StatusBar1.SimpleText := 'Serwer chwilowo niedostępny';
  else
    StatusBar1.SimpleText := ErrorMessage;
  end;
end;

Pełna lista API

Generowana z deklaracji w kodzie (Source/*.pas): wszystkie opublikowane właściwości i zdarzenia TNominatimSearchProvider (także dziedziczone), właściwości publiczne i metody publiczne.

Właściwości opublikowane (29)

Właściwość	Typ	Domyślnie	Opis
`Language`	`string`		Język wyników i komunikatów (pl, en, de …)
`Limit`	`Integer`	`10`	Maksymalna liczba wyników
`ConnectTimeout`	`Integer`	`5000`	Limit czasu połączenia (ms)
`Timeout`	`Integer`	`15000`	Limit czasu odpowiedzi (ms)
`UserAgent`	`string`		Nagłówek User-Agent – identyfikuj aplikację
`MinRequestIntervalMs`	`Integer`	`1000`	Minimalny odstęp między zapytaniami (kolejka); Nominatim: 1000
`RateLimitBackoffMs`	`Integer`	`10000`	Przerwa po HTTP 429
`BaseURL`	`string`		Adres serwera Nominatim
`TokenRequired`	`Boolean`	`True`	Wymagaj tokenu
`TokenFormat`	`TMapTokenFormat`	`mtfAuto`	Sposób przekazania tokenu (mtfAuto, nagłówek, parametr)
`OutputFormat`	`TNominatimFormat`	`nfJSONv2`	Format odpowiedzi (jsonv2, geojson…)
`Outputs`	`TNominatimOutputs`	`[noAddressDetails]`	Dodatkowe dane (adres, extratags, namedetails…)
`CountryCodes`	`string`		Filtr krajów ISO (np. pl,de)
`Layers`	`TNominatimLayers`	`[]`	Warstwy Nominatim (address, poi, railway…)
`FeatureType`	`TNominatimFeatureType`	`nftNone`	Typ obiektu (country, state, city, settlement)
`ExcludePlaceIds`	`string`		Wykluczone place_id
`ViewBox`	`string`		Preferowany obszar lon1,lat1,lon2,lat2
`Bounded`	`Boolean`	`False`	Tylko wyniki w ViewBox
`Dedupe`	`Boolean`	`True`	Usuwanie duplikatów
`Polygon`	`TNominatimPolygon`	`npNone`	Zwracany kształt (geojson, kml, svg, text)
`PolygonThreshold`	`Double`		Uproszczenie kształtu
`Email`	`string`		E-mail kontaktowy (polityka Nominatim)
`DetailsOptions`	`TNominatimDetailsOptions`		Opcje zapytania /details
`Continent`	`TMapContinent`	`mcAuto`	Kontynent (mcAuto = według widoku)
`ContinentFilter`	`Boolean`	`False`	Filtruj wyniki do kontynentu
`SendContinentHint`	`Boolean`	`True`	Wysyłaj podpowiedź kontynentu
`ContinentBaseURLs`	`TStrings`		Serwery per kontynent (eu=…, as=…)
`CheckServerStatus`	`Boolean`	`True`	Sprawdzaj /status przed pierwszym zapytaniem
`StatusCacheSeconds`	`Integer`	`300`	Ważność wyniku /status (s)

Zdarzenia (3)

Zdarzenie	Typ	Opis
`OnResults`	`TMapSearchResultsEvent`	Wyniki wyszukiwania
`OnError`	`TMapSearchErrorEvent`	Każdy błąd (ErrorKind, HTTP, komunikat PL/EN)
`OnConnectionChecked`	`TMapConnectionCheckedEvent`	Wynik sprawdzenia połączenia

Właściwości publiczne – tylko w kodzie (9)

Właściwość	Typ	Opis
`Busy`	`Boolean`	Trwa zapytanie
`HostBaseURL`	`string`	Adres ustawiony przez mapę (gdy BaseURL pusty)
`HostToken`	`string`	Token ustawiony przez mapę
`LastCheckOK`	`Boolean`	Wynik ostatniego sprawdzenia
`LastCheckTime`	`TDateTime`	Czas ostatniego sprawdzenia
`LastCheckErrorKind`	`TMapProviderErrorKind`	Rodzaj błędu sprawdzenia
`LastCheckMessage`	`string`	Komunikat sprawdzenia
`LastStatusJSON`	`string`	Odpowiedź /status
`Token`	`string`	Token – tylko w kodzie (nie w DFM/FMX)

Metody publiczne (17)

Metoda	Opis
`procedure Search(const Query: string)`	Wyszukiwanie (OnResults / callback)
`procedure SearchInArea(const Query: string; const Area: TMapArea)`	Wyszukiwanie w zaznaczonym obszarze
`procedure Reverse(const Lat, Lon: Double; Zoom: Integer = 18)`	Odwrotne geokodowanie
`procedure CancelPending`	Anuluje oczekujące zapytania
`function SupportsKind(Kind: TMapSearchKind): Boolean`	Czy obsługuje rodzaj zapytania
`function RedactedURL(const Request: TMapSearchRequest): string`	URL z ukrytymi sekretami
`function Scrub(const Text: string): string`	Zastępuje sekrety ***
`function EffectiveBaseURL(C: TMapContinent = mcNone): string`	Faktycznie używany adres
`function Params(const Request: TMapSearchRequest): TNominatimParams`	Wszystkie parametry zapytania
`function Validate(out ErrorKind: TMapProviderErrorKind; out ErrorMessage: string): Boolean`	Walidacja (token + URL) bez sieci
`procedure SearchStructured(const Query: TNominatimStructuredQuery)`	Wyszukiwanie strukturalne (ulica, miasto, kod…)
`procedure Lookup(const OsmIds: string)`	/lookup po osm_ids (maks. 50)
`procedure Details(OsmType: Char; OsmId: Int64; const ClassName: string = '')`	/details obiektu
`procedure DetailsByPlaceId(PlaceId: Int64)`	/details po place_id
`procedure CheckConnection(const Callback: TMapConnectionCheckProc = nil)`	/status teraz
`procedure Status`	Alias CheckConnection
`procedure InvalidateConnectionCache`	Zapomina wynik /status

Pełny opis wszystkich właściwości: dokumentacja komponentów map.

Zobacz też

VCLFMXniewidoczny

TCustomUrlSearchProvider

Dowolny geokoder opisany szablonami URL – odpowiedź w formacie Nominatim lub GeoJSON.

▶ Demo na żywo

VCLkontrolka

TTileMapVCL

Mapa kafelkowa dla aplikacji Windows (VCL) – OpenStreetMap, zdjęcia satelitarne, mapa terenu.

▶ Demo na żywo