Autocomplete and fuzzy search

VERSION 0.3.34
PUBLIC PREVIEW

Fuzzy search is the default, generic search service. It can handle vague and imprecise inputs and supply results for:

  • Areas on the map (countries, states, cities).
  • Specific addresses with a street name and number (2501 Soquel Drive, Kalverstraat 23).
  • Address ranges on streets where address points are interpolated along the length of the street.
  • Streets.
  • Junctions, places where two streets intersect.
  • Point of interest (Restaurant, Sports Center).

Fuzzy search requests are built using the FuzzySearchOptions class. You can take advantage of the default parameters in Kotlin, or use FuzzySearchOptions.Builder to choose the properties that you need. The only required parameter for fuzzy search is the query parameter. The other parameters are optional.

1val query = "TomTom"
2val fuzzySearchOptions = FuzzySearchOptions.Builder(query)
3 .countrySet(setOf("NL", "PL"))
4 .limit(5)
5 .build()

To get the best experience, consider:

  • Using maxFuzzyLevel to balance between performance and breadth of results. It can also be tuned to reduce unusual results.
  • Using position to perform geo-biasing, which boosts the priority of results relevant to the user’s current location.
  • Using radius if geo-biasing is not strong enough to keep your results local to the user.
  • Using idx to limit results to specific categories, e.g.: POIs or addresses only

More information about best practices are described here. A detailed description of fuzzy search and its parameters can be found in the Search API Fuzzy Search documentation.

Once you have a FuzzySearchOptions object, provide it to the fuzzy search request. This can be done asynchronously using the FuzzySearchCallback, or synchronously as described in Synchronous search call. If the call succeeds, the returned result is in FuzzySearchResponse. If an error occurred, it is in FuzzySearchError.

1searchApi.fuzzySearch(
2 fuzzySearchOptions,
3 object : FuzzySearchCallback {
4 override fun onSuccess(result: FuzzySearchResponse) {
5 /* YOUR CODE GOES HERE */
6 }
7
8 override fun onError(error: FuzzySearchError) {
9 /* YOUR CODE GOES HERE */
10 }
11 }
12)

Autocomplete

Autocomplete helps users make more effective searches. It recognizes entities inside an input query and offers them as query terms. This improves the accuracy of the search results.

Autocomplete requests are built using the AutocompleteSearchOptions class or its builder AutocompleteSearchOptions.Builder. The required parameters are the query and the language in which autocomplete results should be returned. You can also provide optional parameters to perform a more accurate search, following similar recommendation as for fuzzy search. See also more information in the Search API Autocomplete documentation.

1val query = "Sport"
2val amsterdam = GeoCoordinate(52.379189, 4.899431)
3val autocompleteSearchOptions = AutocompleteSearchOptions.Builder(
4 query = query,
5 language = "en-US"
6)
7 .position(amsterdam)
8 .radius(5000)
9 .build()

Once you have a AutocompleteSearchOptions object, provide it to the autocomplete search request. This can be done asynchronously using the AutocompleteSearchCallback, or synchronously as described in Synchronous search call. If the call succeeds, the returned result is in AutocompleteSearchResponse. If an error occurred, it is in AutocompleteSearchError.

1searchApi.autocompleteSearch(
2 autocompleteSearchOptions,
3 object : AutocompleteSearchCallback {
4 override fun onSuccess(result: AutocompleteSearchResponse) {
5 /* YOUR CODE GOES HERE */
6 }
7
8 override fun onError(error: AutocompleteSearchError) {
9 /* YOUR CODE GOES HERE */
10 }
11 }
12)