Search area

This article describes the behavior of the parameters locality, preferBBox, preferNear and preferNearPrecision, which affect:

  • where the search will take place (restriction of results to an area),
  • how the results will be ranked (preference inside and near a specific area).

These parameters can be used in the functions: Geocode and Suggest.

Recommended usage

  • If you want results primarily around the user’s current location:
    Use preferNear (+ preferNearPrecision, e.g. 5km), do not use locality.
    → Works globally, prioritizes the area around the location.
  • If you want results ideally from a specific area, but others are acceptable:
    Use one of the preference options (preferBBox or preferNear), do not use locality.
  • If you want results only from a specific area (country, region, city):
    Use locality – preferably via BBox (faster and more precise than text).
    Do not combine with a preferred area unless necessary.
  • Combination of locality + preferred area:
    → Suitable only for specific scenarios (e.g. a taxi company: doesn’t want rides outside the city, but within the city prefers results from the center).
    → You must respect the intersection rule, otherwise the API will return an error.

Parameters

locality

  • Type: list of values (country code: cz, gb, us, … , or BBox: {minLon},{minLat},{maxLon},{maxLat})
  • Meaning: hard filter – results are returned only from this area.
  • Multiple values: several localities separated by commas can be specified. Results will be returned from any of them.
  • Optional.

preferBBox

  • Type: BBox in the format {minLon},{minLat},{maxLon},{maxLat}
  • Meaning: soft preference – results inside and near the rectangle are preferred, but if there are not enough relevant results there, the search continues everywhere.
  • Alternative: used instead of preferNear (cannot be combined).
  • Optional, but if not specified, it is set automatically – see “Default behavior” section.

preferNear + preferNearPrecision

  • Type:
    • preferNear = coordinates of a point {lon},{lat}
    • preferNearPrecision = number, circle radius in meters
  • Meaning: define a circle (center + radius). Results inside and near the circle are preferred, but if there are not enough relevant results there, the search continues everywhere.
  • Alternative: used instead of preferBBox (cannot be combined).
  • Optional, but if not specified, it is set automatically – see “Default behavior” section.

Default behavior

  • Without locality and without a preferred area (preferBBox / preferNear):
    → preferred area = BBox around the Czech Republic (default state).
  • Only locality:
    → results are restricted to this area,
    → preferred area is automatically set to locality.
  • Only a preferred area:
    → results are not geographically restricted,
    → results inside and near the preferred area have higher priority.

Combination of locality and preferred area

  • It is possible to combine them, but:
    • the preferred area must intersect with at least one of the specified locality.
    • if they do not intersect → the input is invalid and the API returns an error.

Example of an invalid combination:
locality=cz and preferNear=Paris → preference is outside the Czech Republic, the request fails.

Example of a valid combination:
A taxi service operates within a city:

  • preferBBox = bounding box of the city (results from the city are prioritized),
  • locality = wider circle (e.g. 100 km) so that results are only from the surroundings.

Result ranking when using a preferred area

  1. Inside the preferred area: ranking purely by query relevance.
  2. Near the preferred area: relevance + distance from the area → closer results are returned first.
  3. Far from the area: lower priority.