Find a location

Fuzzy search

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    buildTextSearchOptions(
4        query = "TomTom",
5        geoBias = GeoPoint(latitude = 52.379189, longitude = 4.899431),
6        limit = 20,
7    )

For the best experience, consider:

• Using geoBias to perform geo-biasing, which boosts the priority of results relevant to the user’s current location.
• 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. You can achieve this asynchronously by using an instance of SearchCallback, or synchronously by obtaining a SearchResponse following the instructions outlined in the section called Making search API calls.

If the call succeeds, the returned result is in the SearchResponse. If an error occurred, it is in the SearchFailure.

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

Search by text

You can also create SearchOptions for text-based search using the buildTextSearchOptions helper. It provides the most common parameters for text search with sensible defaults for others.

1val textOptions = buildTextSearchOptions(
2    query = "coffee",
3    geoBias = GeoPoint(latitude = 52.379189, longitude = 4.899431),
4    language = Locale.CHINESE,
5    limit = 20,
6)

Use the resulting SearchOptions with the standard search call (sync or async) following the instructions in Making search API calls.

Search by POI category

Use buildPoiCategorySearchOptions to search for Points of Interest by category, for example restaurants, gas stations, or hotels:

1val poiCategoryOptions = buildPoiCategorySearchOptions(
2    categoryIds = setOf(
3        CategoryId(StandardCategoryId.Restaurant),
4        CategoryId(StandardCategoryId.Cafe),
5    ),
6    geoBias = GeoPoint(latitude = 52.3765, longitude = 4.9054),
7    language = Locale.ENGLISH,
8    limit = 25,
9)

Use the resulting SearchOptions with the standard search call (sync or async) following the instructions in Making search API calls.

If multiple categories are provided, results may include POIs that belong to any of the specified categories. Child categories are included automatically.

Search by brand

Brand search allows you to find specific brand locations, such as McDonald’s, Starbucks, or other well-known chains.

Use buildBrandSearchOptions to search for POIs of a specific brand:

1val brand = Brand("McDonald's")
2val geoBias = GeoPoint(latitude = 52.377956, longitude = 4.897070)
3
4val brandSearchOptions = buildBrandSearchOptions(
5    brand = brand,
6    geoBias = geoBias,
7    language = Locale.ENGLISH,
8    limit = 15,
9)

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.

Route points must be adjusted to the desired route section before passing them to this API.

To specify the request parameters, use the SearchOptions class.

1lateinit var route: Route
2lateinit var routeProgress: RouteProgress
3val routePoints = route.routePoints
4val distanceAlongRoute = routeProgress.distanceAlongRoute
5
6val remainingRoutePoints = routePoints.drop(
7    routePoints.indexOfLast { it.routeOffset <= distanceAlongRoute }.coerceIn(routePoints.indices),
8)
9
10val searchOptions = buildAlongRouteWithPoiCategorySearchOptions(
11    polyline = remainingRoutePoints.map { it.coordinate },
12    categoryIds = setOf(CategoryId(StandardCategoryId.GasStation)),
13    maxDetourDuration = 15.minutes,
14    sortOrder = SortOrder.ByDetourTime,
15    limit = 10,
16)

The request can be performed using instructions as described in the section called Making search API calls.

If you use an asynchronous call, provide a SearchCallback. A successful request returns a SearchResponse. If the request fails, a SearchFailure is returned.

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

Search along route with POI category

You can use buildAlongRouteWithPoiCategorySearchOptions to create search options for finding POIs along a route with specific categories:

1val routePoints = listOf(
2    GeoPoint(latitude = 52.377956, longitude = 4.897070),
3    GeoPoint(latitude = 52.380000, longitude = 4.900000),
4    GeoPoint(latitude = 52.385000, longitude = 4.910000),
5)
6
7val alongRouteWithPoiCategorySearchOptions = buildAlongRouteWithPoiCategorySearchOptions(
8    polyline = routePoints,
9    categoryIds = setOf(CategoryId(StandardCategoryId.GasStation)),
10    maxDetourDuration = 15.minutes,
11    sortOrder = SortOrder.ByDetourTime,
12    language = Locale.ENGLISH,
13)

When conducting a search along a route, the number of points in the polyline influences bandwidth usage. A route with more points consumes more data.

1val searchOptions = SearchOptions(
2    route = routePoints,
3    categoryIds = setOf(CategoryId(StandardCategoryId.GasStation)),
4    maxDetourDuration = 15.minutes,
5)

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 AutocompleteOptions class. Use buildAutocompleteOptions.

Once you have an AutocompleteOptions object, provide it to the Autocomplete search request. This can be done asynchronously using the AutocompleteCallback, or synchronously as described in Making search API calls.

If the call succeeds, the returned result is in the AutocompleteResponse. If an error occurred, it is in the SearchFailure.

1search.autocompleteSearch(
2    autocompleteOptions,
3    object : AutocompleteCallback {
4        override fun onSuccess(result: AutocompleteResponse) {
5            // YOUR CODE GOES HERE
6        }
7
8        override fun onFailure(failure: SearchFailure) {
9            // YOUR CODE GOES HERE
10        }
11    },
12)

Building autocomplete options

Use buildAutocompleteOptions to create autocomplete options with sensible defaults:

1val geoBias = GeoPoint(latitude = 52.377956, longitude = 4.897070)
2
3val autocompleteOptions = buildAutocompleteOptions(
4    query = "cafe",
5    geoBias = geoBias,
6    language = Locale.ENGLISH,
7    limit = 5,
8)

1val autocompleteOptions = AutocompleteOptions(
2    query = query,
3    locale = Locale("en", "US"),
4    position = amsterdam,
5    radius = Distance.meters(5000),
6)

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

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

Search with geometry data request

A Geometry data request is used to obtain geometries that represent the outline of a city, county, or land area. The request supports batch requests for up to twenty (20) identifiers per call. The request with more then twenty (20) identifiers will fail. To build the geometry data request, use the GeometryDataOptions class. The only required parameter is a list of identifiers for which you want geometry. To obtain these identifiers, you must first get the SearchResultId of a fuzzy search. Then use its geometryId property to get the geometry ID.

Not every SearchResult has a geometry ID.

val geometries = fuzzySearchResponse.results.mapNotNull { it.searchResultId.geometryId }

You can provide an optional zoom level parameter, which defines the precision of the returned geometries. For more information about the additional data search, go to the Search API Additional Data Search documentation.

1val geometryDataOptions =
2    GeometryDataOptions(
3        geometryIds = geometries,
4        geometryZoom = null,
5    )

After constructing the GeometryDataOptions object, provide it to the geometry data request. This can be achieved asynchronously using an instance of GeometryDataCallback, or synchronously by obtaining a GeometryDataResponse following the instructions outlined in the section called Making search API calls.

The call returns a GeometryDataResponse object or a SearchFailure if the request is unsuccessful.

1search.requestGeometryData(
2    geometryDataOptions,
3    object : GeometryDataCallback {
4        override fun onSuccess(result: GeometryDataResponse) {
5            // YOUR CODE GOES HERE
6        }
7
8        override fun onFailure(failure: SearchFailure) {
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:

• Point of interest details
• Reverse geocoding