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

Viewport places plugin

The Viewport Places plugin shows search results for the visible map area, and searches again each time the map moves. It connects the SDK's search to the Places module, one module per search you add.

Use cases

How it works

API reference:

ViewportPlaces

Installation

npm install @tomtom-org/maps-sdk maplibre-gl @tomtom-org/maps-sdk-plugin-viewport-places

@tomtom-org/maps-sdk is a peer dependency. Set up a TomTomMap as in Project setup, then add a search:

import { ViewportPlaces } from '@tomtom-org/maps-sdk-plugin-viewport-places';

const viewportPlaces = new ViewportPlaces(map);
await viewportPlaces.addPOICategories({
  id: 'restaurants',
  categories: ['RESTAURANT'],
  minZoom: 10
});

The restaurants places now follow the visible map area from zoom 10.

Place modules stack in the order you add them, with the first one at the bottom and later ones on top.

The viewport places example above stacks two category searches under a brand search.

Usage examples

Add base-map POI categories (styled like the base map)

addPOICategories searches the given POI categories and draws them with the base-map marker type, like the style's own POIs:

await viewportPlaces.addPOICategories({
  id: 'base-pois',
  categories: ['PARKING_GARAGE', 'CHARGING_LOCATION'],
  minZoom: 10,
  maxZoom: 17
});

Add a branded search place module (custom marker type)

add takes a placesModuleConfig, whose marker type defaults to base-map, and any fuzzy search options except geoBias, cursor and signal, which the plugin sets itself:

const brandPlaces = await viewportPlaces.add({
  id: 'brand-search',
  searchOptions: { query: 'Lidl', filters: { poiCategories: ['SUPERMARKET'] }, limit: 20 },
  minZoom: 8,
  placesModuleConfig: { markerType: 'pin' }
});

brandPlaces.events.places.on('click', (place) => console.log(place.properties.poi?.name));

Update an existing place module

await viewportPlaces.update({
  id: 'brand-search',
  searchOptions: { query: 'Aldi', limit: 30 },
  placesModuleConfig: { markerType: 'base-map' }
});

Remove a place module

viewportPlaces.remove('brand-search');
viewportPlaces.removeAll();

Handle errors

add, addPOICategories and update reject with what failed, so an await lands in your catch. The refreshes on map move run without anyone awaiting them, and so does the clear of a search that remove or removeAll stopped. By default, the plugin logs one that fails with console.warn. To handle it yourself, pass onError to the constructor:

import { SDKServiceError } from '@tomtom-org/maps-sdk/services';

const viewportPlaces = new ViewportPlaces(map, {
  onError: (error) => {
    if (!(error instanceof SDKServiceError)) return;
    if (error.apiErrorCode === 'InvalidReferer') showMessage('Add this domain to the API key');
    else if (error.code === 'INSUFFICIENT_PERMISSIONS') showMessage('Enable the Search API for the API key');
  }
});

Related guides and examples