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 mask.

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 masking)

• Specify only the fields needed (for example: title, subtitles, address, openingHours, contacts) to optimize latency and bandwidth.
• Provide minimal vs. rich masks per screen (list view vs. detailed card).

Quick start

Tip

• Locate (one place): /suggest with partial text and context -> select a candidate -> GET /details with a minimal or rich attribute mask.
• Discover (list and select result): /discover with poiTypes, query, and geometry -> /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 app journeys

Locate flow

1. User types a place name. App sends /suggest 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.

Discover flow

1. User opens “Restaurants near me.” App calls /discover with filters.poiTypes and preferences.geometry; minimal attributes for fast lists.
2. On selection, app calls /details to fetch richer attributes before showing the place screen.

Best practices

• Design attribute masks per screen: list (title, subtitles) vs. detail (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.