Developer

Search

VERSION 0.67.0

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 can be created using the SearchOptions struct.

Some useful parameters include:

More information about best practices is described at Best Practices. 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 Search.search(options:completion:) API.

1let options = SearchOptions(query: "Pizza")
2onlineSearch.search(options: options) { result in
3    switch result {
4    case let .success(searchResponse):
5        // handle success
6        break
7    case let .failure(error):
8        // handle error
9        break
10    }
11}

Search along a route

Use this search to find POIs along a specific route with the fuzzy search algorithm. The search is constrained by a time limit for detours from the route. The route must consist of at least 2 points. You can use the Routing module to create a route.

See the instructions in the planning a route guide. Note that route points may need to be adjusted to the needed section before passing them to this API. To create the request, you need to construct a SearchOptions with SearchOptions.route. You can also specify more detailed options for the underlying Fuzzy Search. More information about the Along Route Search can be found in the Search API Along Route Search documentation.

1let route: Route = currentRoute
2let progress: RouteProgress = currentProgress
3

4let remainingRoute = route.routePoints.filter { $0.routeOffset > progress.distanceAlongRoute }
5let remainingCoordinates = remainingRoute.map { $0.coordinate }
6

7let query = "ATM"
8let alongRouteSearchOptions = SearchOptions(
9    query: query,
10    route: remainingCoordinates,
11    maxDetourDuration: Measurement.tt.seconds(600),
12    limit: 10
13)

If the search is successful, results will be returned in SearchResponse.

1onlineSearch.search(options: alongRouteSearchOptions) { result in
2    switch result {
3    case let .success(alongRouteResponse):
4        // handle success
5        break
6    case let .failure(error):
7        // handle error
8        break
9    }
10}

Autocomplete

Autocomplete helps you make more effective searches by suggesting brands and categories, which can be further used in SearchOptions.

Autocomplete requests are built using the AutocompleteOptions struct. The required parameters are the AutocompleteOptions.query. Other parameters can be used to filter the results. Also, see more information in the Search API Autocomplete documentation.

let options = AutocompleteOptions(query: "Piz", locale: Locale(identifier: "en_GB"))

Once you have an AutocompleteOptions object, provide it to the Search.autocomplete(options:completion:) for execution.

1onlineSearch.autocomplete(options: options) { result in
2    switch result {
3    case let .success(autocompleteReponse):
4        // handle success
5        break
6    case let .failure(error):
7        // handle error
8        break
9    }
10}

Geometry search

The geometry search allows you to perform a free-form search inside one or more defined geographic areas.

Following types of geometries are supported:

  • RectangleGeometry - a rectangle defined by BoundingBox.
  • PolygonGeometry - a polygon defined by coordinates of vertices. 
    1let vertices: [CLLocationCoordinate2D] = [
    2    CLLocationCoordinate2D(latitude: 52.377956, longitude: 4.897070),
    3    CLLocationCoordinate2D(latitude: 52.377956, longitude: 4.897070),
    4    CLLocationCoordinate2D(latitude: 52.377956, longitude: 4.897070),
    5    CLLocationCoordinate2D(latitude: 52.377956, longitude: 4.897070),
    6]
    7let polygon = PolygonGeometry(vertices: vertices)
  • CircleGeometry - a circle defined by a center and a radius. 
    let center = CLLocationCoordinate2D(latitude: 52.377956, longitude: 4.897070)
    let circleGeometry = CircleGeometry(coordinate: center, radius: Measurement.tt.meters(1000))

To perform a geometry search, initialize a SearchOptions with SearchOptions.searchAreas parameter and call the Search.search(options:completion:) API. More information about geometry search can be found at Search API Geometry Search documentation.

let options = SearchOptions(query: "Pizza", searchAreas: [.polygon(polygon)])

If the search is successful, the results will be returned in SearchResponse. Otherwise, an Error will be returned.

1let onlineSearch = OnlineSearchFactory.create(apiKey: "YOUR_TOMTOM_API_KEY")
2onlineSearch.search(options: options) { result in
3    switch result {
4    case let .success(geometrySearchResponse):
5        // handle success
6        break
7    case let .failure(error):
8        // handle error
9        break
10    }
11}

Request search result geometries

Search results sometimes have geographic representation, for example, the boundary of a city. With Search.requestGeometryData(options:completion:) API you are able to obtain that boundary. To request geometries, first build a GeometryDataOptions with a list of geometry identifiers, which can be obtained from SearchResultID.geometryDataSourceID of a SearchResult.

Not every SearchResult has this information.

let geometryIDs = searchResponse.results.compactMap { $0.searchResultID.geometryDataSourceID }
let options = GeometryDataOptions(geometryIDs: geometryIDs, geometryZoom: 15)

You can provide an optional zoom level parameter, which defines the precision of geometries. For more information, visit Search API Additional Data Search documentation.

Call Search.requestGeometryData(options:completion:) API with the created options to fetch geometries. The result type is GeometryDataResponse containing GeoJSON features of requested geometries. If the request was unsuccessful, an Error will be returned instead.

1let onlineSearch = OnlineSearchFactory.create(apiKey: "YOUR_TOMTOM_API_KEY")
2onlineSearch.requestGeometryData(options: options) { result in
3    switch result {
4    case let .success(additionalDataResponse):
5        // handle success
6        break
7    case let .failure(error):
8        // handle error
9        break
10    }
11}

Next steps

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