Introduction

The Places Search API is a modern, session-aware search service for discovering, suggesting, and retrieving rich place information. It powers two primary user journeys: locating a single place quickly and discovering nearby places with filters.

Who is it for?

• Frontend/mobile engineers building maps and search UX
• Backend developers enriching datasets with place metadata
• Product teams adding local search, browse, and details to apps.

How it works?

Endpoints

• /suggest: Generates suggestions from partial input using user context and language.
• /discover: Returns a list of places based on query, filters (e.g., poiTypes), and geometry.
• /details: Retrieves rich information for a selected place; controlled via Attributes header.

Sessions and follow-up links

• Session-Id: Send a stable identifier across suggest -> discover -> details to improve relevance and tie events for analytics.
• Follow-up operations: Responses include actionable templates to fetch details or continue discovery, preserving user intent.

Attributes (field selection)

• Specify only the fields needed (for example: title, subtitles, address, openingHours, contacts) to optimize latency and bandwidth.
• Retrieve minimal or extensive set of fields per screen (list view vs. detailed card).

Quick start

Tips

• As-you-type location and discover-action suggestions: /suggest with partial text and context -> select a discover-action suggestion -> /discover with additional context -> select a location -> /details with a minimal or extensive Attributes header.
• Discover POIs /discover with poiTypes, query, and geometry -> /details for selected result.
• Find an address /discover with query and preferred coordinates -> /details for selected result.

Features

• As-you-type predictions with context biasing and follow-up actions.
• Discover with filters (poiTypes, brands).
• Rich details for place cards, including contact info and hours.
• Geometry preference for map viewport–aware results.
• Request headers: Session-Id, Request-Id, Accept-Language, and Attributes.

Typical typing sessions

Finding a place

1. User starts typing a place name. App requests /suggest on (almost) every keypress with Session-Id, Accept-Language, position.
2. User selects a suggestion. App calls /details requesting only fields needed for the card.
3. Render details and focus map at the place or nearest entry point.

Finding an address after typing and pressing enter

1. User types an address with just a street name and a house number. App sends /suggest requests, quick suggestions are not found satisfactory
2. User presses the Search button. App sends /discover request with fully specified query and context. User selects relevant address returned by /discover
3. User adds the address as a destination to calculate route

Discovering a place

1. User starts typing a general topic of interest, for example “burge”, finds a discover-actions suggestion for “Burgers”
2. User selects the “Burgers” suggestion. App calls /discover with filters.poiTypes and preferences.geometry; minimal attributes for fast lists.
3. On selecting a nearby, popular burger joint, app calls /details to show attributes on the place’s details screen.

Best practices

• Request minimal Attributes per screen: list (title, subtitles, distanceInMeters) vs. details (title, subtitles, position, contacts, openingHours).
• Preserve session across all calls tied to the same user interaction.
• Use follow-up links from responses to keep intent and filters consistent.
• Limit response size by using Attributes in the header and request only what you render.
• Internationalize with Accept-Language; test localized naming and sorting.