Search suggestions (places, brands and categories)

getSearchSuggestions() answers “what might the user mean?” in one call. A query like "italian" means both a cuisine category and Ristorante Italiano down the road, and the call returns both in one ranked list. A complete query works as well as a partial one.

Type a few letters into the demo below. Places, brands and categories come back in one list. Pick a brand or category to search it in view.

Basic usage

1
import { getSearchSuggestions } from '@tomtom-org/maps-sdk/services';
2

3
const { suggestions } = await getSearchSuggestions({ query: 'italian' });
4

5
for (const result of suggestions) {
6
    if (result.kind === 'brand' || result.kind === 'category') {
7
        console.log(`Refine by ${result.kind}: ${result.title}`);
8
    } else {
9
        console.log(result.title, result.subtitles);
10
    }
11
}

Result kinds

Every result carries a kind. Narrowing on it tells you what else it carries.

• title is a POI’s name or an address’s first line. subtitles are the remaining address lines. They end with the country only when it differs from the one the results are in.
• id is the place ID getPlaceDetails takes.

A location suggestion carries what a list needs, not the place. To get the full place with its geometry, call resolve() on the one the user picks:

1
const place = await result.resolve();
2
map.flyTo({ center: place.geometry.coordinates });

Acting on a refinement

refine() runs the follow-up search. A brand result searches that brand, and a category result searches that category. Both stay inside the original call’s scope (its filters.countries, filters.boundingBox or geoBias). It works whichever endpoint produced the result:

1
const { suggestions } = await getSearchSuggestions({ query: 'shell' });
2
const brand = suggestions.find((result) => result.kind === 'brand');
3

4
if (brand) {
5
    const stations = await brand.refine();
6
}

• refine() takes an optional AbortSignal. It doesn’t reuse the one given to getSearchSuggestions, because that call has settled by the time you act on a refinement.
• refineParams holds the fuzzy search that refine() runs. You can adjust it and send it yourself:

1
const stations = await discoverPlaces({ ...brand.refineParams, limit: 50 });

Cost

• By default, each call makes two requests, one per arm. Narrowing filters.kinds to only refinement kinds or only location kinds skips the other arm.
• Call resolve() only on the pick, not on the whole list.
• The call doesn’t debounce or cache. Do both per keystroke in your search box’s input loop.

Ranking

The SDK blends the list the way Places Search v3’s suggest does:

• The list leads with at most one brand or category. It is offered only when the whole query names it from the start of a word. pizz offers Pizzeria, while baker st and amster offer none.
• A brand must be backed by the places. One that only starts like the query is dropped unless a leading place carries it, so londo doesn’t offer London Fire Brigade. If filters.kinds leaves out place, no outlets come back to check, so the brand is offered as is.
• Places follow in search order. When the query names a brand or category, places whose names contain the typed words move up, because the suggestion above them already stands for the category.
• If you ask only for refinement kinds, the call returns every recognised refinement instead of the one leader.

Neither backend returns a score comparable with the other’s, so this blend is the SDK’s heuristic, not the API’s.

Parameters

Parameters follow Places Search v3’s suggest body. The full type is SearchSuggestionsParams. It also takes the options every service call takes.

Cancellation

Both arms share one signal, so aborting drops both. A slow arm can’t resolve on its own and refill the list under a newer query. To keep only the newest keystroke’s pair, use createLatestRequest:

1
import { createLatestRequest, getSearchSuggestions } from '@tomtom-org/maps-sdk/services';
2

3
const latestSuggestions = createLatestRequest();
4

5
searchBox.addEventListener('input', async () => {
6
    const response = await latestSuggestions.run((signal) =>
7
        getSearchSuggestions({ query: searchBox.value, signal })
8
    );
9
    if (response.current) showSuggestions(response.value.suggestions);
10
});

If either arm fails, the call rejects with an SDKError whose service is 'SearchSuggestions', instead of returning half a list.

Related guides and examples

• Discover places — where a brand or category refinement’s follow-up runs
• POI categories — the category vocabulary behind category results
• Search playground — getSearchSuggestions() behind a search box