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 a ReverseGeocodingResponse, the nearest addressable location:

• geometry - The point you queried. The point the service matched it to is properties.originalPosition, as Reverse geocoding properties describes.
• properties.type - 'Point Address', 'Street' or 'Geography'. A Geography result also carries its geographyType.
• properties.entryPoints - The address's entrances, unclassified.
• If nothing matches, it's the queried point without properties, and its type says so. Check properties before you read it. The check also narrows the response to a Place you can show.
• There are no dataSources, because a reverse geocoded area has no ID for geometry data. To get its outline, geocode or search for the area.

Enhanced result processing

Address components depend on the location and its data. A city address is detailed, while 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 language and the other options every service call takes. 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 also follows. See Geopolitical views.

Integration patterns

Map click integration

Clicks can come faster than answers, so run each lookup through createLatestRequest. Its section 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. In the Places module, the result's pin sits on the queried point. To place it on the address, first set geometry.coordinates to properties.originalPosition.

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

• If no address is found, you get a place without properties, not an error.
• A failed request rejects with an SDKError. Error handling covers its kinds, including cancellation.
• Ocean and remote points may return only a region or a country.
• Each point costs one request. Pace many points to your key's rate limit, 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 geocode - A coordinate to a pinned address, with the raw response beside it
• Pin interaction - Pins that show their address on click

Related services

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