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"

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

• The geometry ID is place.properties.dataSources.geometry.id, which geocoding and search set on area results (Data sources). Places without one are skipped, so a street address or a POI without an outline adds no polygon.
• Reverse geocoded places have no geometry ID. Geocode or search for the area instead.
• The result is PolygonFeatures, one feature per geometry with the geometry ID as its id. Each feature and the collection have a bbox.
• For a Places collection, each polygon's properties are its place's properties plus placeCoordinates, the place's point, typed as PlaceGeometryProps. A polygon that matches no place of the collection has null properties.
• A Place[] or string[] input returns the polygons with the service's own properties.
• 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, 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 });

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

• 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
• 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