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

Place by ID

VERSION 0.50.4PUBLIC PREVIEW

The Place by ID service retrieves detailed information about a specific place using its unique entity identifier. This is the recommended way to get full place details — including opening hours, categories, and entry points — once you have a place ID.

Basic Usage

Pass the entityId to retrieve a Place with full details, or undefined if the ID is not found:

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


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


if (!place) {
    console.log('Place not found');
    return;
}


const [lng, lat] = place.geometry.coordinates;
console.log(place.properties.poi?.name);            // e.g. 'Rijksmuseum'
console.log(place.properties.address.freeformAddress); // e.g. 'Museumstraat 1, Amsterdam'

Opening Hours

Request opening hours for the upcoming week by setting openingHours:

const place = await placeById({
    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()}`);
    });
}

Retrieve parent or child POI relationships using relatedPois:

// Retrieve child POIs (e.g. terminals inside an airport)
const place = await placeById({
    entityId: '528009002822995',
    relatedPois: 'child',
});


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

Available values: 'child' | 'parent' | 'all' | 'off'

Additional Options

const place = await placeById({
    entityId: '528009002822995',
    openingHours: 'nextSevenDays',
    timeZone: 'iana',       // Include IANA timezone in opening hours
    mapcodes: ['Local', 'International'],  // Alternative location codes
    view: 'Unified',        // Geopolitical view
});

Working with Results

Place by ID returns a Place<SearchPlaceProps> — the same structure as search results — giving you access to the full place detail set:

const place = await placeById({ entityId: '528009002822995' });
if (!place) return;


// Coordinates
const [lng, lat] = place.geometry.coordinates;


// Address
const { freeformAddress, municipality, country } = place.properties.address;


// POI details
const poi = place.properties.poi;
console.log(poi?.name);           // Business name
console.log(poi?.categories);     // e.g. ['MUSEUM']
console.log(poi?.phone);          // Phone number
console.log(poi?.url);            // Website URL

Displaying on the Map

Use PlacesModule.show() to render the retrieved place as a marker on the map:

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


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


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

Integration with POIs Module

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { BaseMapModule, PlacesModule, POIsModule, TomTomMap } from '@tomtom-org/maps-sdk/map';
import { placeById } from '@tomtom-org/maps-sdk/services';
import type { Popup } from 'maplibre-gl';
import './style.css';
import { API_KEY } from './config';
import { buildPopupHtml, createPOIPopup } from './popup';

// (Set your own API key when working in your own environment)
TomTomConfig.instance.put({ apiKey: API_KEY, language: 'en-US' });

(async () => {
    const map = new TomTomMap({
        mapLibre: {
            container: 'sdk-map',
            center: [4.90435, 52.36876],
            zoom: 16,
        },
    });

    const restOfTheMapModule = await BaseMapModule.get(map, { events: { cursorOnHover: 'default' } });
    const poisModule = await POIsModule.get(map);
    const placesModule = await PlacesModule.get(map);

    let activePopup: Popup | null = null;

    const clearSelection = async () => {
        await placesModule.clear();
        activePopup?.remove();
        activePopup = null;
    };

    poisModule.events.on('click', async (feature) => {
        const details = await placeById({
            entityId: feature.properties.id,
            openingHours: 'nextSevenDays',
        });

        if (!details) return;

        await placesModule.show(details);

        activePopup?.remove();
        const [lng, lat] = details.geometry.coordinates;
        activePopup = createPOIPopup().setLngLat([lng, lat]).setHTML(buildPopupHtml(details)).addTo(map.mapLibreMap);
    });

    restOfTheMapModule.events.on('click', async () => {
        await clearSelection();
    });
})();
Open on CodeSandboxOpen Sandbox

A common pattern is to fetch full place details when the user clicks a POI on the map. The POI click event provides the id needed for the lookup:

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


const poisModule = await POIsModule.get(map);


poisModule.events.on('click', async (feature) => {
    const place = await placeById({
        entityId: feature.properties.id,
        openingHours: 'nextSevenDays',
    });


    if (!place) return;
    // Display place on map or show a popup with details
});

See the POIs Module guide for a full walkthrough of this pattern, including popups and map marker integration.

API Reference

For complete documentation of all parameters and response types, see the placeById API Reference.

Map Integration

  • POIs Module - Click on map POIs to get their entity IDs for use with Place by ID
  • Places Module - Display the retrieved place as a marker on the map
  • Search - Find places by query; use their IDs with Place by ID for full details
  • Geocoding - Convert addresses to coordinates for use with routing and map display