Developer

Reverse geocoding

VERSION 1.1.0

The Reverse Geocoding module translates a coordinate (37.786505, -122.3862) into human-understandable information like a street address or street element ("30 The Embarcadero, San Francisco, CA 94111"). Tracking applications use this tool to receive a GPS feed from a device or asset and obtain the corresponding address.

The type of response depends on the available data:

  • address: Returns the most detailed information.
  • street element: Less detailed; returned when there is no address data.
  • geography: Returns the smallest available geographic data.
    • This is returned when there is no address or street element data.
    • You can specify the level of geography to get a geometry (see the areaTypes parameter).

Initializing

To use the Reverse Geocoding SDK, you need to configure its credentials and add the SDK as a dependency:

  1. Get your TomTom API Key and configure the project as described in the Project setup guide.
  2. Add the Reverse Geocoding module dependency in the build.gradle.kts of your application module and synchronize the project. 
    implementation("com.tomtom.sdk.search:reverse-geocoder:1.1.0")
    implementation("com.tomtom.sdk.search:reverse-geocoder-online:1.1.0")

After synchronizing the project, initialize the ReverseGeocoder interface. This interface is the entry point to using TomTom’s Reverse Geocoding SDK. There can be multiple implementations of this interface. However at this moment the only implementation of this interface is OnlineReverseGeocoder.

val reverseGeocoder: ReverseGeocoder = OnlineReverseGeocoder.create(context, "YOUR_API_KEY")

Making a reverse geocoding call

Specify the reverse geocoding request parameters with the ReverseGeocoderOptions class. The only mandatory parameter for the call is the position of the location for which you want to obtain an address. You can also set optional parameters to request more data, like geometry or road use and speed limits. A detailed description of all the parameters can be found in the Reverse Geocoding documentation.

1val coordinate = GeoPoint(52.37650747883495, 4.908392018265384)
2val reverseGeocoderOptions = ReverseGeocoderOptions(
3    position = coordinate
4)

Once you have a ReverseGeocoderOptions object, provide it to the reverse geocoding request. This can be done asynchronously using the ReverseGeocoderCallback, or synchronously as described in Synchronous search call. If the call succeeds, the returned result is in ReverseGeocoderResponse. If an error occurred, it is in SearchError.

1reverseGeocoder.reverseGeocode(
2    reverseGeocoderOptions,
3    object : ReverseGeocoderCallback {
4        override fun onSuccess(result: ReverseGeocoderResponse) {
5            /* YOUR CODE GOES HERE */
6        }
7

8        override fun onFailure(failure: SearchFailure) {
9            /* YOUR CODE GOES HERE */
10        }
11    }
12)
Reverse Geocoding

Next steps

Since you have learned how to reverse geocode, here are recommendations for the next steps: