TomTom Maps SDK for JavaScript
This is the documentation of version 0.51.3. Go to the latest version, 1.0.0-rc.5.

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.

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:

Basic Reverse Geocoding Usage

Simple Coordinate to Address Conversion

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

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

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

const address = result.features[0]?.properties.address;
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:

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

const place = result.features[0];

if (place?.properties.address) {
    const addr = place.properties.address;
    console.log(addr.streetName);       // "Dam"
    console.log(addr.municipality);     // "Amsterdam"
    console.log(addr.country);          // "Netherlands"
    console.log(addr.freeformAddress);  // Complete formatted address
}

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:

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

Parameter Effects:

Result Quality and Relevance

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

Quality Factors:

Integration Patterns

Map Click Integration

Implement reverse geocoding for interactive map experiences:

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

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

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

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

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

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:

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

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

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

Batch Processing

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

async function reverseGeocodeMultiple(coordinates) {
    const results = await Promise.all(
        coordinates.map(coord =>
            reverseGeocode({ position: coord })
        )
    );

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

// Usage example
const waypoints = [
    [4.9041, 52.3676],
    [2.3522, 48.8566],
    [13.4050, 52.5200]
];

const addresses = await reverseGeocodeMultiple(waypoints);

Error Handling and Edge Cases

Robust Error Management

Implement comprehensive error handling for various scenarios:

async function safeReverseGeocode(position, options = {}) {
    try {
        const result = await reverseGeocode({
            position,
            radius: options.radius || 1000,
            ...options
        });

        if (result.features.length === 0) {
            return {
                success: false,
                message: 'No address found for coordinates'
            };
        }

        return {
            success: true,
            address: result.features[0].properties.address
        };

    } catch (error) {
        return {
            success: false,
            message: `Reverse geocoding failed: ${error.message}`
        };
    }
}

Common Edge Cases:

Performance Optimization

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

Caching Strategy:

const reverseGeocodeCache = new Map();

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

    if (reverseGeocodeCache.has(key)) {
        return reverseGeocodeCache.get(key);
    }

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

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

Related Examples

Related Services