Search

VERSION 0.3.1056
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 SearchOptions class. You can take advantage of the default parameters in Kotlin 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 searchOptions =
3 SearchOptions(query, countryCodes = setOf("NLD", "PLD"), limit = 5)

To get the best experience, consider:

  • Using fuzzyLevel to balance between performance and breadth of results. It can also be tuned to reduce unusual results.
  • Using geoBias to perform geo-biasing, which boosts the priority of results relevant to the user’s current location.
  • Using searchAreas if geo-biasing is not strong enough to keep your results local to the user.
  • Using categoryIds 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 SearchOptions object, provide it to the fuzzy search request. This can be done asynchronously using the SearchCallback, or synchronously as described in Synchronous search call. If the call succeeds, the returned result is in SearchResponse. If an error occurred, it is in SearchError.

1search.search(
2 searchOptions,
3 object : SearchCallback {
4 override fun onSuccess(result: SearchResponse) {
5 /* YOUR CODE GOES HERE */
6 }
7
8 override fun onError(error: SearchError) {
9 /* YOUR CODE GOES HERE */
10 }
11 }
12)

Search along the route

Search along the route allows you to perform a POI search along a specified route. This search is constrained by specifying a limit on the amount of time detours can take. If the route that passes through the found point is faster than the original one, the detour time value is negative.

The proposed detour may alter the original route, because the best detour may skip some of the original points.

To specify the request parameters, use the AlongRouteSearchOptions class.

1val query = "ATM"
2val alongRouteSearchOptions = AlongRouteSearchOptions(
3 query = query,
4 route = route.geometry,
5 maxDetourDuration = 600.seconds,
6 sortBy = SortBy.DetourDistance,
7 limit = 10
8)

The request can be performed synchronously or asynchronously. If you use an asynchronous call, provide an AlongRouteSearchCallback. A successful request returns AlongRouteSearchResponse. If the request fails, SearchError is returned.

1search.alongRouteSearch(
2 alongRouteSearchOptions,
3 object : AlongRouteSearchCallback {
4 override fun onError(error: SearchError) {
5 /* YOUR CODE GOES HERE */
6 }
7
8 override fun onSuccess(result: AlongRouteSearchResponse) {
9 /* YOUR CODE GOES HERE */
10 }
11 }
12)

center

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. The required parameter is the query for 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 = GeoPoint(52.379189, 4.899431)
3val autocompleteSearchOptions = AutocompleteSearchOptions(
4 query = query,
5 locale = Locale("en", "US"),
6 position = amsterdam,
7 radius = Distance.meters(5000)
8)

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 SearchError.

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

Search with geographical filter

The search with geographical filter for search results allows you to perform a free-form search inside one or more defined geographic areas (geometries). By default, POIs are returned as a result. For other result types, the categoryIds parameter should be used.

There are two types of geometries that are supported:

  • PolygonGeometry - an array of coordinates of vertices.
    1val vertices = listOf(
    2 GeoPoint(52.377956, 4.897070),
    3 GeoPoint(53.377956, 4.897070),
    4 GeoPoint(53.377956, 5.897070),
    5 GeoPoint(52.377956, 5.897070)
    6)
    7val polygonGeometry = PolygonGeometry(vertices)
  • CircleGeometry - center coordinates and a radius in meters.
    1val center = GeoPoint(52.377956, 6.897070)
    2val radiusInMeters = 1000
    3val circleGeometry = CircleGeometry(center, radiusInMeters)

Provide the geometries and query to the constructor of the SearchOptions by defining the searchAreas parameter. You can also define optional parameters such as the number of results to return, language, and various search constraints. More information about optional parameters and the geometry search can be found in the Search API Geometry Search documentation.

1val query = "Restaurant"
2val geometrySearchOptions = SearchOptions(
3 query = query,
4 searchAreas = setOf(polygonGeometry, circleGeometry)
5)

The search call can be done synchronously or asynchronously. Calling it asynchronously requires a SearchCallback, to handle the response. If the search is successful, the response is a SearchResponse object. Otherwise, error information is returned as a SearchError.

1search.search(
2 geometrySearchOptions,
3 object : SearchCallback {
4 override fun onSuccess(result: SearchResponse) {
5 /* YOUR CODE GOES HERE */
6 }
7
8 override fun onError(error: SearchError) {
9 /* YOUR CODE GOES HERE */
10 }
11 }
12)

Next steps

Since you have learned how to work with search, here are recommendations for the next steps: