Geometry data

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

The demo below geocodes Schiphol Airport, fetches its outline and shows it with the Geometries module.

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. Wrap a single Place in an array.
zoom number Level of detail, 0 to 22. By default, 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, so 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 });

Custom styling configuration covers the module's fill, line and label styling.

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

To list the areas of one geography type in a country or a bounding box, geocode an empty query with that filter:

const regions = await geocode({
    query: '',
    limit: 100,
    filters: { countries: ['FR'], geographyTypes: ['CountrySubdivision'] },
});

// geometryData takes up to 20 places per call
const outlines = [];
for (let i = 0; i < regions.features.length; i += 20) {
    const batch = regions.features.slice(i, i + 20);
    outlines.push(...(await geometryData({ geometries: batch, zoom: 8 })).features);
}
await geometriesModule.show({ type: 'FeatureCollection', features: outlines });

For a bounding box, pass geoBias: { boundingBox } instead of countries. The result is the areas of that type in the country or the box, not the children of a named area. One call returns up to 100 of them. Past that, pass the response's nextCursor back as cursor, as Multiple result handling shows, for up to 2,000. The SDK has no lookup for an area's administrative subdivisions. Which levels hold data varies by country.

Search inside an area

A geometry search takes the result 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