This is the documentation of version 1.0.0-rc.3. Go to the latest version, 1.0.0-rc.5.

Function geometryData

geometryData<P extends CommonPlaceProps>(
    params: Partial<Omit<GlobalConfig, "displayUnits">> & {
        signal?: AbortSignal;
        validateRequest?: boolean;
    } & { zoom?: number } & { geometries: Places | Place[] } & {
        geometries: Places<P>;
    },
): Promise<PolygonFeatures<PlaceGeometryProps<P> | null>>
Retrieves polygon geometries representing geographic area boundaries.

The Geometry Data service returns coordinate sets that define the outlines of geographic areas such as cities, countries, administrative regions, or POI footprints. Use these polygons to visualise area boundaries, for spatial analysis and in geofencing applications.
Type Parameters
- P extends CommonPlaceProps
Parameters
- params: Partial<Omit<GlobalConfig, "displayUnits">> & {
      signal?: AbortSignal;
      validateRequest?: boolean;
  } & { zoom?: number } & { geometries: Places | Place[] } & {
      geometries: Places<P>;
  }
  The geometry IDs or places to fetch boundaries for.
  - Optionalsignal?: AbortSignal
    
    An AbortSignal used to cancel the request.
    
    Remarks
    Aborting rejects the call with an SDKAbortError (its name is 'AbortError') and cancels the underlying HTTP request, including while the SDK is waiting to retry a rate-limited (429) response. Aborting a call that already completed has no effect.
    
    To add a deadline, compose signals: AbortSignal.any([mine, AbortSignal.timeout(5000)]).
    
    Example
    Keep only the latest search with createLatestRequest:
    
    const latestSearch = createLatestRequest(); const search = await latestSearch.run((signal) => discoverPlaces({ query, signal })); if (search.current) showResults(search.value);
    
    Default Value
    undefined (the request cannot be cancelled)
  - OptionalvalidateRequest?: boolean
    
    Whether the SDK validates the request parameters against the expected schema before sending them.
    
    Remarks
    To skip validation, set it to false. The commonBaseURL check (INSECURE_BASE_URL) runs either way.
    
    Default Value
    true
  - Optionalzoom?: number
    
    Optional zoom level for geometry detail.
    
    Remarks
    It controls the level of detail in the returned geometry:
    
    Lower zoom (0-5): Simplified geometry for continents/countries
    
    Medium zoom (6-12): Moderate detail for regions/cities
    
    High zoom (13-22): Full detail for neighborhoods/buildings
    
    Align it with your map's current zoom level, and use a lower zoom for large geographies to reduce data size. Setting it is essential for performance with very large areas.
    
    Default
    undefined (returns highest detail available)
    
    Minimum
    0
    
    Maximum
    22
    
    Example
    zoom: 10 // City-level detail zoom: 15 // Neighborhood-level detail
  - geometries: Places | Place[]
    
    Places or place array containing geometry IDs.
    
    Remarks
    The places must have geometry data sources with IDs. Places without geometry IDs are skipped.
    
    It accepts an array of Place objects or a Places FeatureCollection.
    
    Example
    // FeatureCollection from search geometries: searchResults // Array of places geometries: [place1, place2, place3]
  - geometries: Places<P>
Returns Promise<PolygonFeatures<PlaceGeometryProps<P> | null>>
Polygon features of the area boundaries.
Remarks
You can fetch up to 20 geometries in a single call, at scales from countries down to building footprints, as standard GeoJSON Polygon/MultiPolygon features.

Use it to display city or country boundaries on maps, show POI building footprints, create geofences for spatial queries, visualise administrative divisions, or calculate areas and spatial relationships.

It returns polygons, not places, so pass the result to GeometriesModule.show(), not PlacesModule.show(). The geometryId comes from a prior search result.

A Places collection gets each polygon its place's properties, as PlaceGeometryProps. A polygon the service returns for no place of the collection has null properties. A Place[] or geometry IDs return the polygons with the service's own properties.
Example
```
// Fetch geometry by ID
const cityBoundary = await geometryData({
  geometries: ['geometry-id-123']
});

// Fetch multiple geometries at once
const boundaries = await geometryData({
  geometries: ['country-id-1', 'city-id-2', 'poi-id-3']
});

// Fetch and merge with place data
const searchResults = await discoverPlaces({ query: 'Amsterdam' });
const withBoundaries = await geometryData({
  geometries: searchResults  // Places with geometry IDs
});
// Each polygon carries its place's properties, or null for none
withBoundaries.features[0].properties?.address.freeformAddress;
```
See
geometryData(params: GeometryParams): Promise<PolygonFeatures>
Retrieves polygon geometries representing geographic area boundaries.

The Geometry Data service returns coordinate sets that define the outlines of geographic areas such as cities, countries, administrative regions, or POI footprints. Use these polygons to visualise area boundaries, for spatial analysis and in geofencing applications.
Parameters
- params: GeometryParams
  The geometry IDs or places to fetch boundaries for.
Returns Promise<PolygonFeatures>
Polygon features of the area boundaries.
Remarks
You can fetch up to 20 geometries in a single call, at scales from countries down to building footprints, as standard GeoJSON Polygon/MultiPolygon features.

Use it to display city or country boundaries on maps, show POI building footprints, create geofences for spatial queries, visualise administrative divisions, or calculate areas and spatial relationships.

It returns polygons, not places, so pass the result to GeometriesModule.show(), not PlacesModule.show(). The geometryId comes from a prior search result.

A Places collection gets each polygon its place's properties, as PlaceGeometryProps. A polygon the service returns for no place of the collection has null properties. A Place[] or geometry IDs return the polygons with the service's own properties.
Example
```
// Fetch geometry by ID
const cityBoundary = await geometryData({
  geometries: ['geometry-id-123']
});

// Fetch multiple geometries at once
const boundaries = await geometryData({
  geometries: ['country-id-1', 'city-id-2', 'poi-id-3']
});

// Fetch and merge with place data
const searchResults = await discoverPlaces({ query: 'Amsterdam' });
const withBoundaries = await geometryData({
  geometries: searchResults  // Places with geometry IDs
});
// Each polygon carries its place's properties, or null for none
withBoundaries.features[0].properties?.address.freeformAddress;
```
See