Geocoding

geocode() turns an address or a place name into coordinates. It tolerates typos and partial addresses, and covers street addresses, intersections and areas from neighbourhoods to countries. It returns no POIs. To find a business or a landmark, use discoverPlaces(). Pass query as plain text. The SDK encodes it, and a value you already encoded is encoded again and can resolve to a different place.

The Node.js geocoding example prints the GeoJSON geocode returns for a street name.

Basic geocoding usage

Simplest single address geocoding

geocodeOne returns the best match, and throws an SDKError with the code NOT_FOUND when there is none:

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] } });

Standard address geocoding

geocode returns every candidate. If nothing matches, it returns an empty collection instead of an error. Like geocodeOne, it takes the query string on its own or the params object:

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

const result = await geocode('Dam Square, Amsterdam, Netherlands');

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

// The params form sets every other option, such as `limit` or `signal`
const firstFive = await geocode({ query: 'Main Street', limit: 5 });

Filtering results

filters holds every option that drops results, by country and by geography type.

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

• countries - Takes ISO 3166-1 alpha-2 or alpha-3 codes.
• geographyTypes - Restricts Geography results to types such as Municipality or PostalCodeArea.
• There are no POI filters. Geocoding has no notion of POIs, so the rest of search's filters doesn't apply.

Advanced geocoding configuration

Geographic constraints and biasing

geoBias takes a point or a rectangle, as it does for search. A point ranks nearer results higher, and with radiusMeters it confines them to a circle. A rectangle confines them to its area.

const nearAmsterdam = await geocode({
    query: 'Central Station',
    geoBias: { position: [4.9041, 52.3676] },
    filters: { countries: ['NL'] },
});

const inBox = await geocode({
    query: 'Main Street',
    geoBias: { boundingBox: [4.7, 52.2, 5.1, 52.5] }, // [west, south, east, north]
});

Other parameters

Besides query, limit (up to 100, default 10), filters, geoBias and cursor, geocoding takes these parameters and the options every service call takes:

The full type is GeocodingParams.

Geopolitical view

geopoliticalView decides which country an address in a disputed territory belongs to, and defaults to the global one. Geocoding supports fewer views than the other places services. For a view it doesn't support, it uses the default for the caller's country. Geopolitical views lists them.

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

Multiple result handling

An ambiguous name returns several candidates, so the user can pick one:

const results = await geocode({ query: 'Paris', limit: 5 });

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

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

To fetch the next page, pass the response's properties.nextCursor back as cursor with the same parameters, as in search pagination.

Working with geocoding results

Result data structure

Each feature is a Place whose type is an address, a street, a cross street or a Geography, never a POI. Besides the place properties, it carries matchConfidence.score, which says how well the result's text matches the query:

const result = await geocode({ query: 'Damrak 1, Amsterdam' });
const place = result.features[0];

const [longitude, latitude] = place.geometry.coordinates;
const { freeformAddress, streetName, streetNumber, municipality, postalCode, country } = place.properties.address;

console.log(place.properties.type);                  // e.g. 'Point Address'
console.log(place.properties.matchConfidence.score); // higher is a closer textual match

Address lists every address component.

Integration with mapping

The Places module shows the result as it is:

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

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

await placesModule.show(await geocode({ query: 'Museumplein, Amsterdam' }));

Performance and best practices

• When you know the country or the area, narrow the search with filters and a geoBias. Results get more relevant and ambiguous names resolve.
• Cache frequent lookups yourself, since the SDK doesn't.
• Handle no match, which is an empty collection from geocode or a NOT_FOUND SDKError from geocodeOne. A failed request rejects with an SDKError too. Error handling covers its codes.

Related guides and examples

Map integration

• Places module - Geocoded locations on the map
• Routing module - Geocoded addresses as route waypoints

Related examples

• Geocode - A place name to a pin, with the map opened on its bbox
• Waypoints - Geocoded addresses as route waypoints
• Map route reconstruction playground - A route between geocoded locations, reshaped by a drawn trail

Related services

• Reverse geocoding - Coordinates to an address
• Discover places - POIs and free-text search
• Route planning parameters - Routes between geocoded locations