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

Geocoding

The Geocoding service converts addresses and place names into precise geographic coordinates, providing detailed location information including formatted addresses, place categories, and geographic boundaries. This service is essential for location-based applications that need to transform human-readable addresses into mappable coordinates.

Core geocoding concepts

Geocoding serves as the bridge between human-readable location descriptions and machine-processable geographic coordinates. The service handles various input formats, from complete street addresses to partial location descriptions, and returns structured geographic data suitable for mapping and analysis.

Primary Use Cases:

Basic geocoding usage

Simplest single address geocoding

For the quickest way to geocode a single address when you only need the top result, use geocodeOne:

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

const place = await geocodeOne('Dam Square, Amsterdam, Netherlands');
const coordinates = place.geometry.coordinates; // [longitude, latitude]

// The params form takes everything `geocode` does except `limit`
const biased = await geocodeOne({ query: 'Main Street', geoBias: { position: [4.9041, 52.3676] } });

This convenience function automatically returns just the most relevant result, making it ideal for simple address lookups where you don't need multiple candidates or additional configuration.

Standard address geocoding

When you need more control over the geocoding results or want to retrieve multiple candidates, use the standard geocode function:

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

const result = await geocode({
    query: 'Dam Square, Amsterdam, Netherlands'
});

const coordinates = result.features[0].geometry.coordinates; // [longitude, latitude]

This approach provides access to all geocoding parameters and returns the full result set, allowing you to handle multiple matches or apply advanced filtering.

Filtering results

Everything that drops results lives under filters: the countries a result may come from, and the geography types it may be.

const result = await geocode({
    query: 'Utrecht',
    filters: { countries: ['NL'], geographyTypes: ['Municipality'] }
});

Advanced geocoding configuration

Geographic constraints and biasing

Control geocoding results by applying geographic constraints that bias results toward specific regions or limit search scope:

// Bias results toward Amsterdam area
const result = await geocode({
    query: 'Central Station',
    geoBias: { position: [4.9041, 52.3676] }, // Amsterdam center coordinates
    filters: { countries: ['NL'] }
});

// Search within a specific bounding box
const result = await geocode({
    query: 'Main Street',
    geoBias: { boundingBox: [4.7, 52.2, 5.1, 52.5] }, // Amsterdam metropolitan area
});

Geographic Constraint Benefits:

Geopolitical view

geopoliticalView decides which country an address in a disputed territory belongs to, and defaults to the global one. Geocoding serves fewer views than the other places services; a view it does not serve leaves the default for the caller's country. See Geopolitical views.

const result = await geocode({ query: 'Laayoune', geopoliticalView: 'MA' });

Multiple result handling

When dealing with ambiguous location names or when you need alternative options, request multiple geocoding candidates:

const results = await geocode({
    query: 'Paris', // Matches multiple cities worldwide
    limit: 5
});

results.features.forEach(place => {
    const address = place.properties.address;
    console.log(`${address.municipality}, ${address.country}`);
    console.log(place.geometry.coordinates); // [longitude, latitude]
});

// The next five, if there are any
const nextCursor = results.properties?.nextCursor;
const more = nextCursor && (await geocode({ query: 'Paris', limit: 5, cursor: nextCursor }));

The response's properties.nextCursor, passed back as cursor with the same parameters, fetches the next page; it works as it does for search pagination.

This approach is particularly valuable for:

Working with geocoding results

Result data structure

Geocoding results follow the GeoJSON specification and provide comprehensive location information:

const result = await geocode({
    query: 'Amsterdam Central Station'
});

const place = result.features[0];

// Extract coordinate information
const [longitude, latitude] = place.geometry.coordinates;

// Access detailed address components
const address = place.properties.address;
console.log(address.freeformAddress);  // Complete formatted address
console.log(address.municipality);     // Amsterdam
console.log(address.country);          // Netherlands
console.log(address.postalCode);       // Postal code if available

// Retrieve place category information
console.log(place.properties.poi?.categories); // ['RAILWAY_STATION']

Address Component Hierarchy:

Integration with mapping

Geocoding results integrate seamlessly with the TomTom Maps SDK for immediate visualization:

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

const map = new TomTomMap({ mapLibre: { container: 'map' } });
const placesModule = await PlacesModule.create(map);

const result = await geocode({
    query: 'Amsterdam Museum District'
});

// Display geocoded location on map
await placesModule.show(result);

Performance and best practices

Optimization strategies

For production applications processing multiple addresses, implement these optimization techniques:

Caching Strategy:

Request Optimization:

Error Handling:

try {
    const result = await geocode({
        query: 'Nonexistent Address 123'
    });

    if (result.features.length === 0) {
        console.log('No results found for the given address');
        // Handle no results scenario
    }
} catch (error) {
    console.error('Geocoding failed:', error.message);
    // Implement fallback strategies
}

For comprehensive geocoding implementation examples and advanced usage patterns, go to the examples gallery.

Related guides and examples

Map integration

Related examples

Related services