Reverse geocoding

reverseGeocode() turns coordinates, such as a map click or a GPS fix, into the address at that point.

Basic reverse geocoding usage

Simple coordinate to address conversion

import { reverseGeocode } from '@tomtom-org/maps-sdk/services';

const place = await reverseGeocode({ position: [4.9041, 52.3676] }); // [longitude, latitude]

console.log(place.properties?.address?.freeformAddress); // e.g. "Dam, 1012 Amsterdam, Netherlands"

position takes [longitude, latitude] or any GeoJSON carrying a point. The call resolves one Place, the nearest addressable location:

• geometry is the point you queried. The point the service matched it to is properties.originalPosition, as Reverse geocoding properties describes.
• properties.type is 'Point Address', 'Street' or 'Geography'; a Geography result also carries its geographyType.
• properties.entryPoints lists the address's entrances, unclassified.
• No match leaves properties out, so guard it as above.
• No dataSources: a reverse geocoded area has no ID geometry data takes. Geocode or search for the area to get its outline.

Enhanced result processing

Address components depend on the location and the data there: a city address is detailed, a remote point may only name its region. Address lists every component.

const address = place.properties?.address;
if (address) {
    console.log(address.streetName, address.streetNumber, address.municipality, address.country);
}

Advanced configuration options

It also takes the options every service call takes, language among them. The full type is ReverseGeocodingParams.

// The nearest address within 100 m, in English
const nearby = await reverseGeocode({ position: [4.9041, 52.3676], radiusMeters: 100, language: 'en-GB' });

// The municipality the point is in
const municipality = await reverseGeocode({ position: [4.9041, 52.3676], geographyTypes: ['Municipality'] });

// The street matched along an eastward heading
const onTheRoad = await reverseGeocode({ position: [4.9041, 52.3676], heading: 90 });

A small radiusMeters is more precise but may find nothing in sparse areas.

Geopolitical view

In a disputed territory, the country an address belongs to depends on the geopolitical view. The same point in Gilgit is in Pakistan from the international view and in India from the Indian one:

const unified = await reverseGeocode({ position: [74.31, 35.92], geopoliticalView: 'Unified' });
const indian = await reverseGeocode({ position: [74.31, 35.92], geopoliticalView: 'IN' });
// unified.properties.address.country: 'Pakistan', indian.properties.address.country: 'India'

geopoliticalView defaults to the global one, which the map follows too; see Geopolitical views.

Integration patterns

Map click integration

Clicks can come faster than answers, so run each lookup through createLatestRequest, which also covers what a retired lookup resolves to, cancel() and deadlines:

import { TomTomMap } from '@tomtom-org/maps-sdk/map';
import { createLatestRequest, reverseGeocode } from '@tomtom-org/maps-sdk/services';

const map = new TomTomMap({ mapLibre: { container: 'map' } });
const latestLookup = createLatestRequest();

map.mapLibreMap.on('click', async (event) => {
    const lookup = await latestLookup.run((signal) =>
        reverseGeocode({ position: event.lngLat.toArray(), signal })
    );
    if (!lookup.current) return; // a newer click retired this lookup

    const address = lookup.value.properties?.address?.freeformAddress;
    if (address) showAddress(address);
});

The reverse geocoding playground adds a pin and an address popup. To show the result with the Places module, the pin sits on the queried point; set geometry.coordinates to properties.originalPosition first to place it on the address.

GPS location processing

navigator.geolocation.getCurrentPosition(async ({ coords }) => {
    const place = await reverseGeocode({ position: [coords.longitude, coords.latitude], radiusMeters: 50 });

    const currentAddress = place.properties?.address;
    if (currentAddress) displayCurrentLocation(currentAddress.freeformAddress);
});

Error handling and edge cases

• No address found resolves a place without properties, not an error.
• A failed request rejects with an SDKError; Error handling covers its kinds, cancellation included.
• Ocean and remote points may return only a region or a country.
• Many points at once cost one request each: send them at a pace your key's rate limit allows, and cache answers for points you look up repeatedly, rounding the coordinates for the cache key.

Related guides and examples

Map integration

• Places module - Reverse geocoded locations on the map
• User interaction events - The map clicks that trigger a lookup

Related examples

• Reverse geocoding playground - A lookup per map click, with a pin and an address popup
• Geopolitical views playground - The address of a place in a disputed territory, from each geopolitical view
• Reverse geocoding JSON - The raw response data
• Pin interaction - Pins that show their address on click

Related services

• Geocoding - Addresses to coordinates
• Discover places - Places around a point