Oblast vyhledávání

Tento článek popisuje chování parametrů locality, preferBBox, preferNear a preferNearPrecision, které ovlivňují:

  • kde se bude hledat (omezení výsledků na oblast),
  • jak se budou výsledky řadit (zvýhodnění uvnitř a v blízkosti určité oblasti).

Tyto parametry lze používat ve funkcích: Geocode i Suggest.

Doporučené použití

  • Chcete-li výsledky primárně kolem aktuální polohy uživatele:
    Používejte preferNear (+ preferNearPrecision např 5km), nepoužívejte locality.
    → Funguje celosvětově, preferuje okolí polohy.
  • Chcete-li výsledky ideálně z nějaké oblasti, ale nevadí i jiné:
    Použijte jednu z prefer možností (preferBBox nebo preferNear), nepoužívejte locality.
  • Chcete-li výsledky pouze z nějaké oblasti (stát, kraj, město):
    Použijte locality – ideálně přes BBox (rychlejší a přesnější než text).
    Nekombinujte s preferovanou oblastí, pokud to není nutné.
  • Kombinace locality + preferovaná oblast:
    → Vhodné jen ve specifických scénářích (např. taxi firma: nechce jezdit mimo město, ale v rámci města preferuje výsledky přímo z centra).
    → Je nutné pohlídat pravidlo průniku, jinak API vrátí chybu.

Parametry

locality

  • Typ: seznam hodnot ( kód státu: cz, gb, us, … , nebo BBox: {minLon},{minLat},{maxLon},{maxLat})
  • Význam: tvrdý filtr – výsledky se vrací pouze z této oblasti.
  • Více hodnot: lze zadat více lokalit oddělených čárkou. Výsledky se pak vrací z libovolné z nich.
  • Nepovinné.

preferBBox

  • Typ: BBox ve formátu {minLon},{minLat},{maxLon},{maxLat}
  • Význam: měkká preference – výsledky uvnitř a v blízkosti obdélníku jsou preferovány, ale není list dost relevatních výsledků zde, hledá se všude.
  • Alternativa: používá se místo preferNear (nelze kombinovat).
  • Nepovinné, ale pokud není vyplněno, nastaví se automaticky – viz sekce „Výchozí chování“.

preferNear + preferNearPrecision

  • Typ:
    • preferNear = souřadnice bodu {lon},{lat}
    • preferNearPrecision = číslo, poloměr kružnice v metrech
  • Význam: určují kružnici (střed + poloměr). Výsledky uvnitř a v blízkosti kružnice jsou preferovány, ale není list dost relevatních výsledků zde, hledá se všude.
  • Alternativa: používají se místo preferBBox (nelze kombinovat).
  • Nepovinné, ale pokud není vyplněno, nastaví se automaticky – viz sekce „Výchozí chování“.

Výchozí chování

  • Bez locality i bez preferované oblasti (preferBBox / preferNear):
    → preferovaná oblast = BBox kolem ČR (výchozí stav).
  • Pouze locality:
    → výsledky jsou omezeny na tuto oblast,
    → preferovaná oblast se automaticky nastaví na locality.
  • Pouze preferovaná oblast:
    → výsledky nejsou geograficky omezené,
    → výsledky uvnitř a v blízkosti preferované oblasti mají vyšší prioritu.

Kombinace locality a preferované oblasti

  • Je možné kombinovat, ale:
    • preferovaná oblast se musí protínat alespoň s jednou zadanou locality.
    • pokud se neprotínají → zadání je nevalidní a API vrátí chybu.

Příklad nevalidní kombinace:
locality=cz a preferNear=Paříž → preference je mimo ČR, dotaz selže.

Příklad validní kombinace:
Taxi služba funguje v rámci města:

  • preferBBox = obálka města (výsledky z města mají přednost),
  • locality = širší kružnice (např. 100 km), aby výsledky byly jen z okolí.

Řazení výsledků při použití preferované oblasti

  1. Uvnitř preferované oblasti: řazení čistě podle relevance dotazu.
  2. V blízkosti preferované oblasti: relevance + vzdálenost od oblasti → bližší jsou vraceny přednostně.
  3. Daleko od oblasti: nižší priorita.