Developer

Additional Data

VERSION 0.32.0

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. 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 = GeometryDataOptions(
2    geometryIds = geometries,
3    geometryZoom = null
4)

Once the GeometryDataOptions object is built, you can perform either a synchronous or asynchronous request. The call returns an GeometryDataResponse object, or a SearchFailure if the request was 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)

POI details request

The data relating to a POI in the search result list is incomplete. The POI detail request is used to obtain all available details about the POI. It does this by using the ID that is delivered in the search results. To build the POI details request, use the PoiDetailsOptions class. The only required parameter is an identifier of the POI for which you want to get details. To obtain the identifier, get the SearchResultId of the selected SearchResult of a fuzzy search.

Only results of the POI type SearchResult are supported by the POI details request API.

The POI identifiers from the online and offline sources are incompatible. This means that the hybrid execution mode is not available for POI detail requests. If HybridSearchApi is used, only one request is executed (online or onboard), depending on the source of the identifier.

val searchResultId = searchResponse.results.firstOrNull()?.searchResultId ?: return
val poiId = PoiId(searchResultId.id, searchResultId.source)

You can also provide an optional locale parameter, to define the language choice of the delivered results. For more information about the POI details request, go to the Search API Place by ID documentation.

1val poiDetailsOptions = PoiDetailsOptions(
2    poiId = poiId,
3    locale = Locale("fr", "FR")
4)

Once the PoiDetailsOptions object is built, you can perform either a synchronous or asynchronous request. The call returns a PoiDetailsResponse object, or a SearchFailure if the request was unsuccessful.

1search.requestPoiDetails(
2    poiDetailsOptions,
3    object : PoiDetailsCallback {
4        override fun onSuccess(result: PoiDetailsResponse) {
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 result details, here are recommendations for the next steps: