TomTom LogoDocs
Products
Resources
Pricing
Sign in
Maps SDK for JavaScript
Introduction
Guides
Examples
API Reference

Geometry data

VERSION 1.0.0-rc.3PUBLIC PREVIEW

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"
ParameterTypeDescription
geometriesPlaces | 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.
zoomnumberLevel 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.

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