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

Place details

VERSION 1.0.0-rc.7PUBLIC PREVIEW

getPlaceDetails() fetches one place by its ID, with the opening hours, related POIs and EV charging hardware a search result can carry. The ID comes from:

  • a search result’s id, which sits on the feature, not in its properties
  • a related POI’s id
  • a search suggestion’s id
  • a click on the map’s own POIs, below

Basic usage

The call resolves to a Place, or undefined when the ID matches nothing:

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


const place = await getPlaceDetails({ entityId: '528009002822995' });


if (place) {
    console.log(place.properties.poi?.name);
    console.log(place.properties.address.freeformAddress);
}

The place has the same SearchPlaceProps as a search result. Places describes every property.

Opening hours

const place = await getPlaceDetails({ entityId: '528009002822995', openingHours: 'nextSevenDays' });


const hours = place?.properties.poi?.openingHours;
if (hours?.alwaysOpenThisPeriod) {
    console.log('Open 24/7');
} else {
    hours?.timeRanges.forEach(({ start, end }) => {
        console.log(`Open ${start.date.toLocaleString()} – ${end.date.toLocaleString()}`);
    });
}

relatedPois takes 'child' (such as the terminals of an airport), 'parent', 'all' or 'off' (the default):

const place = await getPlaceDetails({ entityId: '528009002822995', relatedPois: 'child' });


place?.properties.relatedPois?.forEach((related) => {
    console.log(related.id, related.relationType);
});

Additional options

const place = await getPlaceDetails({
    entityId: '528009002822995',
    timeZone: 'iana',                     // the POI's IANA time zone, in poi.timeZone
    mapcodes: ['Local', 'International'], // short location codes, in mapcodes
    geopoliticalView: 'Unified',          // overrides the global view for this call
});

Displaying on the map

The Places module shows the place as it is:

import { TomTomMap, PlacesModule } from '@tomtom-org/maps-sdk/map';
import { getPlaceDetails } from '@tomtom-org/maps-sdk/services';


const map = new TomTomMap({ mapLibre: { container: 'sdk-map' } });
const placesModule = await PlacesModule.create(map);


const place = await getPlaceDetails({ entityId: '528009002822995' });
if (place) await placesModule.show(place);

Integration with POIs module

A click on one of the map’s own POIs carries the id the lookup takes. Clicks can come faster than answers, so run each lookup through createLatestRequest, as the demo above does:

import { POIsModule } from '@tomtom-org/maps-sdk/map';
import { createLatestRequest, getPlaceDetails } from '@tomtom-org/maps-sdk/services';


const poisModule = await POIsModule.get(map);
const latestLookup = createLatestRequest();


poisModule.events.on('click', async (feature) => {
    const lookup = await latestLookup.run((signal) =>
        getPlaceDetails({ entityId: feature.properties.id, openingHours: 'nextSevenDays', signal })
    );
    if (!lookup.current || !lookup.value) return;
    showDetailsPanel(lookup.value);
});

The POIs module guide covers the click event and what its feature carries.

Map integration

  • POIs module - The map’s own POIs, whose clicks carry the ID getPlaceDetails() takes
  • Places module - The retrieved place on the map