Specialized search

VERSION 0.3.34
PUBLIC PREVIEW

Search along the route

Search along the route allows you to perform a fuzzy search for POIs 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, either directly or by using AlongRouteSearchOptions.Builder.

1val query = "ATM"
2val alongRouteSearchOptions = AlongRouteSearchOptions.Builder(
3 query = query,
4 route = route.geometry,
5 maxDetourTime = Duration.ofSeconds(600)
6)
7 .typeAhead(true)
8 .sortBy(SortBy.DETOUR_DISTANCE)
9 .limit(10)
10 .build()

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, AlongRouteSearchError is provided.

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

center

The EV charging stations availability search checks the availability of Electric Vehicle (EV) charging points at a specific charging station. The request parameters are defined using EvChargingStationsAvailabilityOptions. The only mandatory parameter is the charging station identifier. You can get this identifier from the result of a fuzzy search. The identifier is in the AdditionalDataSources of the SearchResult, labeled chargingAvailability.

Not every SearchResult contains charging station information.

val searchResult = fuzzySearchResponse.results.first()
val chargingStationId = searchResult.dataSources?.chargingAvailability?.id ?: return

You can add optional restrictions to the request: connector type, minimum power (expressed in kilowatts) and maximum power (expressed in kilowatts).

1val evChargingStationsAvailabilityOptions = EvChargingStationsAvailabilityOptions(
2 chargingStationId = chargingStationId,
3 connectorTypeSet = setOf("IEC62196Type1", "IEC62196Type1CCS"),
4 minPowerKw = 5.0,
5 maxPowerKw = 15.0
6)

The request can be performed synchronously or asynchronously. If you use an asynchronous call, provide an EvChargingStationsAvailabilityCallback. A successful request returns EvChargingStationsAvailabilityResponse. If the request fails, EvChargingStationsAvailabilityError is provided.

1searchApi.evChargingStationSearch(
2 evChargingStationsAvailabilityOptions,
3 object : EvChargingStationsAvailabilityCallback {
4 override fun onSuccess(result: EvChargingStationsAvailabilityResponse) {
5 /* YOUR CODE GOES HERE */
6 }
7
8 override fun onError(error: EvChargingStationsAvailabilityError) {
9 /* YOUR CODE GOES HERE */
10 }
11 }
12)

Additional 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 additional data search request, use the AdditionalDataSearchOptions class or its builder AdditionalDataSearchOptions.Builder. The only required parameter is a list of identifiers you want to get geometry for. To get these identifiers, first get the AdditionalDataSources of the selected SearchResults of a fuzzy search. Then use its geometry property to get the geometry ID.

Not every SearchResult has this information.

val geometries = fuzzySearchResponse.results.mapNotNull { it.dataSources?.geometry?.id }

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 additionalDataSearchOptions = AdditionalDataSearchOptions(
2 geometries = geometries,
3 geometriesZoom = null
4)

Once the AdditionalDataSearchOptions object is built, you can perform either a synchronous or asynchronous request. The call returns an AdditionalDataSearchResponse object, or an AdditionalDataSearchError if the request did not succeed.

1searchApi.additionalDataSearch(
2 additionalDataSearchOptions,
3 object : AdditionalDataSearchCallback {
4 override fun onSuccess(result: AdditionalDataSearchResponse) {
5 /* YOUR CODE GOES HERE */
6 }
7
8 override fun onError(error: AdditionalDataSearchError) {
9 /* YOUR CODE GOES HERE */
10 }
11 }
12)

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 idx parameter should be used.

There are two types of geometries that are supported:

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

Provide the geometries and query to the constructor of the GeometrySearchOptions or to its builder GeometrySearchOptions.Builder. 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.

1val query = "Restaurant"
2val geometrySearchOptions = GeometrySearchOptions.Builder(
3 query = query,
4 geometries = listOf(polygonGeometry, circleGeometry)
5)
6 .limit(10)
7 .build()

The geometry search call can be done synchronously or asynchronously. Calling it asynchronously requires a GeometrySearchCallback, to handle the response. If the search was successful, the response is presented as a GeometrySearchResponse object. Otherwise, error information is returned as a GeometrySearchError.

1searchApi.geometrySearch(
2 geometrySearchOptions,
3 object : GeometrySearchCallback {
4 override fun onSuccess(result: GeometrySearchResponse) {
5 /* YOUR CODE GOES HERE */
6 }
7
8 override fun onError(error: GeometrySearchError) {
9 /* YOUR CODE GOES HERE */
10 }
11 }
12)