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"

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

• The geometry ID is place.properties.dataSources.geometry.id, set on area results of geocoding and search (Data sources). Places without one are skipped, so a street address or a POI without an outline adds no polygon.
• Reverse geocoded places carry no geometry ID; geocode or search for the area instead.
• The result is PolygonFeatures: one feature per geometry, its id the geometry ID, each feature and the collection with a bbox.
• Passing a Places collection also copies each place's properties onto its polygon, adding placeCoordinates, the place's point. A Place[] or string[] input returns the polygons alone.
• A low zoom returns simplified outlines that are lighter to transfer and draw; match it to the zoom you show the area at.

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

• Geometries module - Showing and styling boundaries on the map
• Places module - The places the outlines belong to

Related examples

• Basic geometry - The outline around a searched area
• Geometries playground - Several outlines, each configured differently
• Places in geometry - Places searched within an outline
• Search places within geometry - Places searched within the area of a location
• Places by category in words - A category named in words, in five languages, searched inside a city outline

Related services

• Discover places - Areas to fetch outlines for, and searches inside them
• Geocoding - Areas by name