Optionalfilters?: DiscoverPlacesCategoryFiltersOptionalsignal?: AbortSignalAn AbortSignal used to cancel the request.
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)]).
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);
OptionalvalidateRequest?: booleanWhether the SDK validates the request parameters against the expected schema before sending them.
OptionalextendedPostalCodesFor?: SearchIndexType[]The indexes for which results include extended postal codes.
Extended postal codes carry more detailed postal code information, including sub-divisions and hierarchical structures.
By default, extended postal codes are included for all indexes except Geo. Geographic entities
can have very long postal code lists, so you must request them explicitly when needed.
A regular postal code is "10001" (basic ZIP code), and an extended one "10001-1234" (ZIP+4 format).
Note that including them for geographies can significantly increase response size.
Optionallimit?: numberThe maximum number of results in a single response, which controls pagination.
Fuzzy search and geocoding page with cursor, as CommonGeocodeAndFuzzySearchParams.cursor describes.
Optionalmapcodes?: MapcodeType[]The mapcode representations to request for locations.
Mapcodes are short, human-friendly location codes that can represent any location on Earth to within a few meters. They're easier to remember and communicate than coordinates.
The mapcode types are:
Local: Short codes valid within a specific territory (e.g., "49.4V" in Netherlands)International: Codes that work globally (e.g., "NLD 49.4V")Alternative: Alternative representations for the same locationUse them for:
Optionalfilters?: PlaceFiltersThe kinds of places that may come back, as PlaceFilters.
OptionalopeningHours?: "nextSevenDays"The format and detail level of the POI opening hours data that the response includes.
Optionalquery?: stringThe text to search for.
It can be a place name, POI, address, or any free-form location query. If you leave it out,
filters alone drive the results (a category, a brand, a fuel type), or geometries do on
geometry search.
For example:
Pass it as plain text. The SDK encodes it for the request path, so a value you already encoded is encoded again and can resolve to a different place.
The query is processed with fuzzy matching to handle typos and variations.
OptionalrelatedPois?: RelatedPoisRequestWhich related POIs the response includes.
Some POIs have hierarchical relationships (e.g., terminal inside airport).
The relationship types are:
off: No related POIs (default)child: Include child POIs (e.g., terminals of an airport)parent: Include parent POIs (e.g., airport of a terminal)all: Include both parent and child relationshipsUse it to:
OptionaltimeZone?: "iana"The timezone information to include for POI locations, for scheduling and time-aware applications.
Maximum allowed detour time in seconds, a positive integer up to 3600 (one hour);
request validation rejects a larger one.
Only POIs reachable within this additional travel time from the route are returned. It controls the width of the search corridor.
Route geometry to search along.
It accepts any of three forms:
Route feature as returned by calculateRoute (most common)LineString GeoJSON geometry objectPosition[], a plain array of [longitude, latitude] coordinate pairsCoordinates must always be in [longitude, latitude] order.
OptionalsortBy?: AlongRouteSortBySort order for the results.
Optionalfilters?: { countries?: undefined }The matching places.
// Free-text search near a location
const results = await discoverPlaces({
query: 'pizza restaurant',
geoBias: { position: [4.9041, 52.3676] }, // Amsterdam
limit: 10
});
// Search within a specific area
const areaResults = await discoverPlaces({
query: 'coffee shop',
geometries: [polygon], // Search within this polygon
limit: 20
});
// Category search
const restaurants = await discoverPlaces({
filters: { poiCategories: ['ITALIAN_RESTAURANT'] },
geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 } // Within 5km
});
// The same, from a category in words
const italian = await discoverPlaces({
filters: { poiCategoryQuery: 'italian food' },
geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 }
});
Finds places by text query, within geometries or along a route, from one universal function.
It runs one of three searches, picked from its params:
route is given, for places within a detour budget of the route.geometries is given, for places inside those areas.geoBias.With a route, each result's properties are AlongRoutePlaceProps, which add the detour a stop
at the place costs.
Optionalfilters?: DiscoverPlacesCategoryFiltersOptionalsignal?: AbortSignalAn AbortSignal used to cancel the request.
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)]).
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);
OptionalvalidateRequest?: booleanWhether the SDK validates the request parameters against the expected schema before sending them.
OptionalextendedPostalCodesFor?: SearchIndexType[]The indexes for which results include extended postal codes.
Extended postal codes carry more detailed postal code information, including sub-divisions and hierarchical structures.
By default, extended postal codes are included for all indexes except Geo. Geographic entities
can have very long postal code lists, so you must request them explicitly when needed.
A regular postal code is "10001" (basic ZIP code), and an extended one "10001-1234" (ZIP+4 format).
Note that including them for geographies can significantly increase response size.
Optionallimit?: numberThe maximum number of results in a single response, which controls pagination.
Fuzzy search and geocoding page with cursor, as CommonGeocodeAndFuzzySearchParams.cursor describes.
Optionalmapcodes?: MapcodeType[]The mapcode representations to request for locations.
Mapcodes are short, human-friendly location codes that can represent any location on Earth to within a few meters. They're easier to remember and communicate than coordinates.
The mapcode types are:
Local: Short codes valid within a specific territory (e.g., "49.4V" in Netherlands)International: Codes that work globally (e.g., "NLD 49.4V")Alternative: Alternative representations for the same locationUse them for:
Optionalfilters?: PlaceFiltersThe kinds of places that may come back, as PlaceFilters.
OptionalopeningHours?: "nextSevenDays"The format and detail level of the POI opening hours data that the response includes.
Optionalquery?: stringThe text to search for.
It can be a place name, POI, address, or any free-form location query. If you leave it out,
filters alone drive the results (a category, a brand, a fuel type), or geometries do on
geometry search.
For example:
Pass it as plain text. The SDK encodes it for the request path, so a value you already encoded is encoded again and can resolve to a different place.
The query is processed with fuzzy matching to handle typos and variations.
OptionalrelatedPois?: RelatedPoisRequestWhich related POIs the response includes.
Some POIs have hierarchical relationships (e.g., terminal inside airport).
The relationship types are:
off: No related POIs (default)child: Include child POIs (e.g., terminals of an airport)parent: Include parent POIs (e.g., airport of a terminal)all: Include both parent and child relationshipsUse it to:
OptionaltimeZone?: "iana"The timezone information to include for POI locations, for scheduling and time-aware applications.
Maximum allowed detour time in seconds, a positive integer up to 3600 (one hour);
request validation rejects a larger one.
Only POIs reachable within this additional travel time from the route are returned. It controls the width of the search corridor.
Route geometry to search along.
It accepts any of three forms:
Route feature as returned by calculateRoute (most common)LineString GeoJSON geometry objectPosition[], a plain array of [longitude, latitude] coordinate pairsCoordinates must always be in [longitude, latitude] order.
OptionalsortBy?: AlongRouteSortBySort order for the results.
Optionalfilters?: { countries?: undefined }The matching places.
// Free-text search near a location
const results = await discoverPlaces({
query: 'pizza restaurant',
geoBias: { position: [4.9041, 52.3676] }, // Amsterdam
limit: 10
});
// Search within a specific area
const areaResults = await discoverPlaces({
query: 'coffee shop',
geometries: [polygon], // Search within this polygon
limit: 20
});
// Category search
const restaurants = await discoverPlaces({
filters: { poiCategories: ['ITALIAN_RESTAURANT'] },
geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 } // Within 5km
});
// The same, from a category in words
const italian = await discoverPlaces({
filters: { poiCategoryQuery: 'italian food' },
geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 }
});
Finds places by text query, within geometries or along a route, from one universal function.
It runs one of three searches, picked from its params:
route is given, for places within a detour budget of the route.geometries is given, for places inside those areas.geoBias.With a route, each result's properties are AlongRoutePlaceProps, which add the detour a stop
at the place costs.
The matching places.
// Free-text search near a location
const results = await discoverPlaces({
query: 'pizza restaurant',
geoBias: { position: [4.9041, 52.3676] }, // Amsterdam
limit: 10
});
// Search within a specific area
const areaResults = await discoverPlaces({
query: 'coffee shop',
geometries: [polygon], // Search within this polygon
limit: 20
});
// Category search
const restaurants = await discoverPlaces({
filters: { poiCategories: ['ITALIAN_RESTAURANT'] },
geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 } // Within 5km
});
// The same, from a category in words
const italian = await discoverPlaces({
filters: { poiCategoryQuery: 'italian food' },
geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 }
});
Finds places by text query, within geometries or along a route, from one universal function.
It runs one of three searches, picked from its params:
routeis given, for places within a detour budget of the route.geometriesis given, for places inside those areas.geoBias.With a
route, each result's properties are AlongRoutePlaceProps, which add the detour a stop at the place costs.