Reverse geocoding

The Reverse Geocoding service converts geographic coordinates into human-readable addresses and location information. This service is essential for applications that need to display location details based on map clicks, GPS coordinates, or other coordinate-based inputs, transforming raw latitude/longitude pairs into meaningful address data.

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { reverseGeocode } from '@tomtom-org/maps-sdk/services';
import { API_KEY } from './config';

TomTomConfig.instance.put({ apiKey: API_KEY });

(async () => {
    const response = await reverseGeocode({ position: [5.72884, 52.33499] });
    console.log(JSON.stringify(response, null, 4));
})();

Core Reverse Geocoding Concepts

Reverse geocoding performs the inverse operation of standard geocoding, taking precise coordinate inputs and returning structured address information. This process involves spatial analysis to determine the most appropriate address or place name for a given geographic point.

Primary Applications:

• Map interaction feedback when users click on map locations
• GPS coordinate interpretation in mobile and navigation applications
• Location labeling for photos, check-ins, and social media posts
• Address discovery for delivery and logistics applications
• Geographic data enrichment in analytics and reporting systems

Basic Reverse Geocoding Usage

Simple Coordinate to Address Conversion

The fundamental reverse geocoding operation converts coordinates into readable address information:

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

3
const result = await reverseGeocode({
4
    position: [4.9041, 52.3676] // Amsterdam Dam Square coordinates
5
});
6

7
const address = result.features[0]?.properties.address;
8
console.log(address.freeformAddress); // "Dam, 1012 Amsterdam, Netherlands"

This basic approach provides the most relevant address information for the specified coordinates, typically returning the nearest addressable location.

Enhanced Result Processing

Process reverse geocoding results to extract specific address components and handle various response scenarios:

1
const result = await reverseGeocode({
2
    position: [4.9041, 52.3676]
3
});
4

5
const place = result.features[0];
6

7
if (place?.properties.address) {
8
    const addr = place.properties.address;
9
    console.log(addr.streetName);       // "Dam"
10
    console.log(addr.municipality);     // "Amsterdam"
11
    console.log(addr.country);          // "Netherlands"
12
    console.log(addr.freeformAddress);  // Complete formatted address
13
}

Address Component Availability: Address components vary based on the coordinate location and available geographic data. Urban areas typically provide more detailed information, while rural or remote locations may return broader regional information.

Advanced Configuration Options

Search Radius and Precision Control

Configure the search scope and precision requirements for reverse geocoding operations:

1
const result = await reverseGeocode({
2
    position: [4.9041, 52.3676],
3
    radius: 100,        // Search radius in meters
4
    language: 'en-GB'   // Response language preference
5
});

Parameter Effects:

• radius: Controls how far from the coordinate to search for addressable features
• language: Determines the language of returned address components and place names
• Smaller radius values provide more precise results but may return no results in sparse areas
• Larger radius values increase the likelihood of finding address information

Result Quality and Relevance

The service prioritizes result relevance based on proximity and address completeness:

Quality Factors:

• Proximity: Closer addresses receive higher priority
• Completeness: Full addresses rank higher than partial information
• Accuracy: Verified addresses take precedence over estimated locations
• Relevance: More specific locations (building addresses) rank above general areas

Integration Patterns

Map Click Integration

Implement reverse geocoding for interactive map experiences:

1
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
2

3
const map = new TomTomMap({ mapLibre: { container: 'map' } });
4

5
map.mapLibreMap.on('click', async (event) => {
6
    const { lng, lat } = event.lngLat;
7

8
    const result = await reverseGeocode({
9
        position: [lng, lat]
10
    });
11

12
    const address = result.features[0]?.properties.address?.freeformAddress;
13
    if (address) {
14
        console.log(`Clicked location: ${address}`);
15
        // Display address in popup or sidebar
16
    }
17
});

This pattern enables users to discover address information by interacting directly with map locations.

GPS Location Processing

Process GPS coordinates from mobile devices or location services:

1
// Get user's current location and convert to address
2
navigator.geolocation.getCurrentPosition(async (position) => {
3
    const { longitude, latitude } = position.coords;
4

5
    const result = await reverseGeocode({
6
        position: [longitude, latitude],
7
        radius: 50 // Precise local search
8
    });
9

10
    const currentAddress = result.features[0]?.properties.address;
11
    if (currentAddress) {
12
        displayCurrentLocation(currentAddress.freeformAddress);
13
    }
14
});

Batch Processing

For applications requiring multiple coordinate conversions, implement efficient batch processing:

1
async function reverseGeocodeMultiple(coordinates) {
2
    const results = await Promise.all(
3
        coordinates.map(coord =>
4
            reverseGeocode({ position: coord })
5
        )
6
    );
7

8
    return results.map(result =>
9
        result.features[0]?.properties.address?.freeformAddress
10
    ).filter(Boolean);
11
}
12

13
// Usage example
14
const waypoints = [
15
    [4.9041, 52.3676],
16
    [2.3522, 48.8566],
17
    [13.4050, 52.5200]
18
];
19

20
const addresses = await reverseGeocodeMultiple(waypoints);

Error Handling and Edge Cases

Robust Error Management

Implement comprehensive error handling for various scenarios:

1
async function safeReverseGeocode(position, options = {}) {
2
    try {
3
        const result = await reverseGeocode({
4
            position,
5
            radius: options.radius || 1000,
6
            ...options
7
        });
8

9
        if (result.features.length === 0) {
10
            return {
11
                success: false,
12
                message: 'No address found for coordinates'
13
            };
14
        }
15

16
        return {
17
            success: true,
18
            address: result.features[0].properties.address
19
        };
20

21
    } catch (error) {
22
        return {
23
            success: false,
24
            message: `Reverse geocoding failed: ${error.message}`
25
        };
26
    }
27
}

Common Edge Cases:

• Ocean coordinates: Return regional or country-level information
• Remote locations: May return broader geographic areas instead of specific addresses
• Invalid coordinates: Handle coordinate validation and error responses
• Service limits: Implement retry logic and rate limiting

Performance Optimization

For applications with frequent reverse geocoding needs, consider these optimization strategies:

Caching Strategy:

1
const reverseGeocodeCache = new Map();
2

3
async function cachedReverseGeocode(position, precision = 0.001) {
4
    // Round coordinates for cache key
5
    const key = `${Math.round(position[0]/precision)*precision},${Math.round(position[1]/precision)*precision}`;
6

7
    if (reverseGeocodeCache.has(key)) {
8
        return reverseGeocodeCache.get(key);
9
    }
10

11
    const result = await reverseGeocode({ position });
12
    reverseGeocodeCache.set(key, result);
13
    return result;
14
}

For complete reverse geocoding implementation examples and advanced integration patterns, go to http://docs.tomtom.com/maps-sdk-js/examples .

Related Guides and Examples

Map Integration

• Places Module - Learn how to display reverse geocoded locations as places on the map with popups and interactions
• User Interaction Events - Handle map click events to trigger reverse geocoding and display results

Related Examples

• Reverse Geocoding with Map Display - Complete example showing reverse geocoding triggered by map clicks with marker placement and address popups
• Reverse Geocoding JSON - Working with reverse geocoding response data structures
• Pin Interaction - Interactive map pins that show reverse geocoded addresses on click

Related Services

• Geocoding - Convert addresses to coordinates (inverse operation)
• Search - Find places and locations that can be displayed using reverse geocoding results