Google Places field masks and pricing, explained

Google Places field masks are not just response-shaping syntax. They are pricing controls.

For Places API (New), Google says Place Details, Nearby Search, and Text Search use field masks to specify returned fields, and the request is billed at the highest SKU that applies to the fields you ask for (usage and billing docs).

That means this is not just a performance concern:

X-Goog-FieldMask: places.displayName,places.formattedAddress,places.location

It is also a billing decision.

The field mask is part of your product scope

A search result row often starts small:

• name
• address
• coordinate
• place type

Then someone asks for rating. Then opening hours. Then photos. Then reviews. Each addition may be reasonable in isolation, but the field mask is where those product asks turn into a different SKU.

Google’s current Places API SKU docs and pricing list are the source to verify before procurement, but the rule of thumb is simple:

The exact tier names and rates can change. The risk pattern is stable: requesting one richer field can reprice the whole call.

Audit masks like code

Field masks deserve the same review discipline as database migrations or public API changes. They affect:

• monthly bill
• latency and payload size
• data retention obligations
• what the UI can promise
• whether you need follow-up Place Details calls

Put masks in named constants, not scattered strings:

const PLACE_SEARCH_FIELDS = [
  "places.id",
  "places.displayName",
  "places.formattedAddress",
  "places.location",
  "places.types",
].join(",");

When someone adds places.rating, make the pull request say “places.rating may move this call to a higher SKU. Check the price table before merging.” That sentence prevents a lot of billing archaeology later.

One syntax caveat: Text Search and Nearby Search field masks use a places. prefix in response fields. Place Details masks use unprefixed field names. Check the endpoint docs before copying a mask between methods.

Avoid the two-call trap

Some teams try to keep search cheap by returning only IDs, then calling Place Details for every result. That can be right for a narrow workflow, but it is not automatically cheaper. If you show 10 results and then hydrate each result with details, one user search can become 11 billable events.

Run the arithmetic against your real UI:

Field masks reduce waste. They do not make every multi-step design cheaper.

Where Good Enough Maps fits

Good Enough Maps has a much smaller response schema: place_id, name, lat, lon, distance_mi, categories, and address fields. There is no field-mask pricing table because there are no ratings, reviews, photos, hours, or atmosphere fields to upsell.

That is a limitation, not a trick. If your product needs rich venue content, use a richer provider. If your product needs backend proximity search and predictable quota caps, a narrower response is often the point.

FAQ

What is a Google Places field mask?

A field mask tells Places API (New) which fields to return. Google uses field masks for Place Details, Nearby Search, and Text Search.

Can a field mask change the bill?

Yes. Google says requests are billed at the highest SKU that applies to the fields requested. Adding one field can move a call into a higher tier.

What is the safest pricing habit?

Request only the fields you render or store, put field masks in named constants, and review pricing impact whenever the mask changes.

Last validated 2026-06-23.