Developer

Search

VERSION 0.34.2

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 struct. The only required parameter for fuzzy search is the SearchOptions.query string parameter. The other parameters are optional.

To get the best experience, consider:

  • Using SearchOptions.geoBias 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 SearchOptions.resultTypes to limit results to specific categories, e.g., POIs or addresses only.

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.

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. To create the request, you must create SearchOptions. The SearchOptions.query, SearchOptions.route, and SearchOptions.maxDetourDuration parameters are required. You can also specify more detailed options for the underlying Fuzzy Search. More information about the Along Route Search is in the Search API Along Route Search documentation.

1let query = "ATM"
2let alongRouteSearchOptions = SearchOptions(
3    query: query,
4    route: route,
5    maxDetourDuration: Measurement.tt.seconds(600),
6    limit: 10
7)

Parameter completion: The completion closure is called after the response to the request has been processed. If no errors occurred, SearchResponse contains an array of categories and subcategories together with their translations and synonyms.

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 users make more effective searches. It recognizes brands and categories 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 struct. The required parameters are the AutocompleteOptions.query and the AutocompleteOptions.locale in which the autocomplete results should be returned. You can also provide optional parameters to perform a more accurate search, following similar recommendations as for fuzzy search. 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.

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 (geometries). By default, POIs are returned as a result. For other result types, the idxSet parameter should be used.

There are two types of geometries that are supported:

  • PolygonGeometry - an array of 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 - center coordinates and a radius in meters. 
    let center = CLLocationCoordinate2D(latitude: 52.377956, longitude: 4.897070)
    let circleGeometry = CircleGeometry(coordinate: center, radius: Measurement.tt.meters(1000))

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

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

If the search was successful, the response is presented as a SearchResponse object. Otherwise, error is returned.

1let onlineSearch = OnlineSearchFactory.create(apiKey: "YOUR_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

The geometry data search is used to obtain geometries to represent the outline of a city, county, or land area. It supports batch requests for up to 20 identifiers per call. To build the Geometry Data search request, use the GeometryDataOptions. The only required parameter is a list of identifiers for which you want to get geometry. To obtain these identifiers, first get the SearchResultID of the selected SearchResults of a Fuzzy Search. Then use its SearchResultID.geometryDataSourceID property to get the geometry ID.

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 the returned geometries. For more information about the additional data search, visit Search API Additional Data Search documentation.

The call returns an GeometryDataResponse object, or an Error if the request was unsuccessful.

1let onlineSearch = OnlineSearchFactory.create(apiKey: "YOUR_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}