A Place ID Connects The Experience
Conceptual OverviewSearch Or Autocomplete
Find places or help a user complete a search.
Place ID
Use the identifier to connect place lookups.
Details And Photos
Request the fields and media your experience needs.
At A Glance
- Provides: Search, place lookup, Autocomplete, and photo retrieval.
- Not: Foot traffic, unrestricted bulk export, or guaranteed field availability.
02 / What's Included
Choose The Endpoint For The Job
Included
- Text Search — free-form query, e.g. "vegan restaurants in Austin"
- Nearby Search — radius + place-type search around a point
- Place Details — the full record for one place ID
- Autocomplete — type-ahead place & address predictions
- Place Photos — imagery served by photo reference
Not Included
- Address ↔ coordinate conversion (Geocoding API)
- Address validation (separate API; no delivery guarantee)
- Turn-by-turn routing (Routes API)
- Bulk place-attribute export for analytics (Places Insights)
Common Request Parameters
Depends On The Endpoint
03 / Search & Ranking
Search That Filters Like A Product, Not Just A Keyword Box
Built-in Filters
- priceLevels and minRating narrow Text Search results in the same call, no second round-trip
- rankPreference reorders Nearby Search by POPULARITY (default) or raw DISTANCE
- evOptions filters for a minimum charging rate and specific connector types — genuine EV-aware search, not a bolt-on
Text Search Filters
Nearby Search Ranking & Scope
04 / Autocomplete Sessions
The Session Ending Determines The Bill
How A Session Works
- Keep one token for one user session; do not reuse completed tokens
- Details Essentials: prediction requests 1–12 are billed; 13 onward use the no-charge session SKU, plus the terminating Details charge
- IDs-only Details termination or an abandoned session: prediction requests revert to per-request pricing
- Other eligible Details termination uses Enterprise + Atmosphere session-termination pricing; Address Validation termination uses Address Validation Enterprise
First 12 predictions billed + Details; later predictions use Session Usage.
Predictions use Session Usage; terminator billed at Details Enterprise + Atmosphere.
Predictions use Session Usage; validation billed at Address Validation Enterprise.
Predictions billed per request.
Assumes correctly formed, eligible sessions. Consult the session-pricing rules for implementation details.
05 / Place Attributes & AI
The Response Is Richer Than A Name And An Address
Notable Fields
- accessibilityOptions exposes wheelchair-accessible entrance, parking, restroom, and seating as individual booleans
- evChargeOptions returns connector type, count, and max charging rate per station
- generativeSummary and reviewSummary are summaries with field-specific availability and attribution requirements, not raw review text
- currentSecondaryOpeningHours covers cases like a separate drive-through or delivery schedule
Real-world Attributes
Hours & Status
Summaries (Enterprise + Atmosphere)
06 / Field Masks & SKUs
Endpoint And Field Mask Set The SKU
The Trap Teams Fall Into
- asking for reviews on a card that only renders a name and a pin pushes the entire call into the priciest tier
- the mask is enforced per request, not per project — two calls to the same endpoint can land in two different SKU tiers
- a leaner mask usually means a smaller, faster response too, not just a cheaper one
id is IDs Only; formattedAddress and location require Essentials.
displayName and other Pro fields raise a Details request to Pro.
rating, userRatingCount, priceLevel, currentOpeningHours, websiteUri.
reviews and applicable summary fields.
This ladder is for Place Details. Text Search and Nearby Search have their own field-to-SKU mappings.
07 / Why Go Through Us
Plan The Integration And Its Operating Cost
| Review Area | Implementation Decision |
|---|---|
| Field Masks | Request only the fields the feature needs; map each to its endpoint’s SKU. |
| Sessions | Test completed, abandoned, IDs-only, and validation-terminated sessions. |
| Migration | Compare request methods, field names, errors, attribution, and costs. |
| Billing | Estimate usage by SKU and cumulative volume band; confirm the account arrangement. |
| Support | Define the support scope, response targets, and escalation process in the agreement. |
Google documentation and support options are available directly. Partner services, pricing, billing consolidation, and response commitments must be confirmed in the applicable proposal.
08 / Legacy → New
Migrate Method By Method
What Changes In The Move
- Text Search and Nearby Search move to POST/JSON; Place Details remains GET
- Translate field names and nesting, then test response handling and attribution
- Compare Legacy data-category charges with New endpoint/field-mask tiers using realistic traffic
Method, path, body, API enablement, and credential restrictions
Field names, masks, missing values, and errors
Session endings, SKU mix, attribution, and feature availability
Run the old and new workflows against representative inputs before switching.
09 / Extend With Maps Platform
A Place ID Is A Key Into The Rest Of Maps Platform
Enable and authenticate each service separately. Places Insights uses BigQuery permissions and dataset access, not a Places API key; commercial scope and billing arrangements should be confirmed.
Pairs Well With
10 / Example Requests
What A Request Actually Looks Like
Selected output fields from an illustrative response
POST https://places.googleapis.com/v1/places:searchText
X-Goog-Api-Key: YOUR_API_KEY
X-Goog-FieldMask: places.displayName,places.rating,places.currentOpeningHours
{"textQuery":"coffee shops in Austin, TX"}
Illustrative output · No request executed
| displayName.text | Rating | currentOpeningHours.openNow |
|---|---|---|
| Example Coffee A | 4.6 | true |
| Example Coffee B | 4.4 | false |
Synthetic points inside the requested 800 m circle
POST https://places.googleapis.com/v1/places:searchNearby
X-Goog-Api-Key: YOUR_API_KEY
X-Goog-FieldMask: places.displayName,places.location,places.types
{"includedTypes":["cafe"],"maxResultCount":2,
"locationRestriction":{"circle":{
"center":{"latitude":30.267,"longitude":-97.743},
"radius":800}}}
Illustrative output · No request executed
| displayName.text | Location | Types |
|---|---|---|
| Example Cafe A | 30.268, -97.744 | cafe |
| Example Cafe B | 30.264, -97.742 | cafe |
11 / Reliability
Plan For Reliability And Recovery
The Commitment
- 99.9% monthly uptime objective for covered services
- Credits require eligibility, a timely claim, and the conditions in the SLA
The Proof
- Use the public status dashboard to investigate incidents
- Preview and Experimental features are subject to their own terms and exclusions
Inspect status and returned fields; missing data is not a successful business decision.
Use bounded retries and backoff for retryable failures; avoid retry storms.
Compare your logs with the public status dashboard and SLA claim requirements.
Availability and result quality are different measures.
12 / Pricing
Estimate Usage By Endpoint And Tier
Estimate cost from expected calls, endpoint-specific field tiers, session endings, and cumulative volume bands. Compare the result with the user experience you need; a review does not guarantee savings.
| Endpoint | Billing Basis |
|---|---|
| Text Search | Highest applicable field tier; IDs-only has its own SKU |
| Nearby Search | Pro, Enterprise, or Enterprise + Atmosphere fields |
| Place Details | Endpoint-specific field tiers; session termination may change billing |
| Autocomplete | Per-request or eligible session rules |
| Place Photos | Photo retrieval SKU, separate from Details |
Billing rules reviewed September 14, 2026. Check current per-SKU prices, free allowances, and cumulative volume bands before quoting. Legacy has its own data-category and session rules; it is not universally flat-priced regardless of fields.
13 / Get Started