This is the documentation of version 0.64.0. Go to the latest version, 1.0.0.

Geometry data

geometryData() fetches the boundary polygons of areas such as countries, regions, cities and neighbourhoods, from the places geocoding or search returned.

Basic usage

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

const places = await geocode({ query: 'Amsterdam, Netherlands' });
const boundaries = await geometryData({ geometries: places, zoom: 10 });

console.log(boundaries.features[0].geometry.type); // "Polygon" or "MultiPolygon"
Parameter Type Description
geometries Places | Place[] | string[] Required. The places, or their geometry IDs, to fetch outlines for. An array holds 1 to 20. A single Place is not accepted; wrap it in an array.
zoom number Level of detail, 0 to 22. Omitted, the service returns its highest detail.

It also takes the options every service call takes. The full type is GeometryDataParams.

Integration with map module

The result is polygons, not places: show it with the Geometries module, not the Places module.

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

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

const places = await geocode({ query: 'Netherlands' });
const boundaries = await geometryData({ geometries: places, zoom: 6 });

await geometriesModule.show(boundaries);
map.mapLibreMap.fitBounds(boundaries.bbox, { padding: 50 });

Fill, line and label styling are module options: Custom styling configuration.

Working with multiple geometries

One call fetches the outlines of several places, such as every geography result of a search:

import { discoverPlaces, geometryData } from '@tomtom-org/maps-sdk/services';

const places = await discoverPlaces({
    query: 'Amsterdam',
    filters: { indexes: ['Geo'] },
    limit: 5,
});
const allBoundaries = await geometryData({ geometries: places, zoom: 12 });

await geometriesModule.show(allBoundaries);

show replaces what the module showed before: to add outlines from separate calls, merge their features into one collection and show that.

Use cases

Administrative boundaries

Countries, regions and cities have outlines; fetch one with the area's name and a zoom that fits its size:

const [province] = (await geocode({ query: 'Utrecht province, Netherlands', limit: 1 })).features;
const outline = await geometryData({ geometries: [province], zoom: 8 });

Search inside an area

The result feeds a geometry search as it is:

const city = await geocode({ query: 'Utrecht, Netherlands', limit: 1 });
const cityOutline = await geometryData({ geometries: city });

const cafes = await discoverPlaces({ query: 'cafe', geometries: [cityOutline] });

Related guides and examples

Related guides

Related examples

Related services