How Fieldmasks Work

Control exactly which fields the API returns. Reduce payload size and get only the data you need.

What is a Fieldmask?

A fieldmask is a comma-separated list of field names passed as the fieldmask parameter in your API request. It tells the API to return only the fields you specify. Omitting the parameter returns all fields, which can result in very large responses. Use fieldmasks to reduce payload size and improve performance.

Syntax

Simple Fields

List the top-level field names you need, separated by commas.

fieldmask=report_key,date,keyword,arp

Dot Notation (Nested Fields)

Access fields inside nested objects using dot notation.

fieldmask=location.name,location.address

Wildcards (Arrays)

Use * to select a field from every item in an array.

fieldmask=businesses.*.name,businesses.*.arp

Per-Endpoint Recipes

Copy-paste these fieldmasks to get the right data from each endpoint without over-fetching.

Endpoint Use Case Fieldmask Recipe
POST /v1/reports/ Browsing scan reports report_key,date,keyword,location.name,arp,atrp,solv,grid_size,platform
POST /v1/reports/{report_key}/ Scan analysis report_key,date,place_id,keyword,location,arp,atrp,solv,found_in,total_competitors,competition_solv,max_solv,opportunity_solv,grid_size,radius,measurement,ai_analysis,image,heatmap
POST /v1/competitor-reports/ Browsing competitors report_key,date,keyword,location.name,grid_size,platform
POST /v1/competitor-reports/{report_key} Competitor analysis date,keyword,grid_size,radius,businesses.*.name,businesses.*.place_id,businesses.*.arp,businesses.*.atrp,businesses.*.solv,businesses.*.reviews,businesses.*.rating,businesses.*.lat,businesses.*.lng
POST /v1/trend-reports/ Browsing trends report_key,last_date,keyword,location.name,location.address,scan_count,arp,arp_move,atrp,atrp_move,solv,solv_move
POST /v1/campaigns/ Browsing campaigns report_key,name,status,locations,keywords,frequency,last_run,next_run,arp,atrp,solv,arp_move,atrp_move,solv_move
POST /v1/campaigns/{report_key} Campaign overview report_key,name,status,locations,keywords,arp,atrp,solv,arp_move,atrp_move,solv_move,frequency,last_run,next_run
POST /v1/guard/ Browsing Guard reports report_key,place_id,location.name,location.address,location.rating,location.reviews,status,date_added,date_last
POST /v1/reviews/ Browsing Reviews reviews_key,name,date,locations,frequency,statistics.metrics.primaryBusiness

The data_points array contains ranking data for every grid coordinate and can be extremely large. It is stripped by default. Only include data_points in your fieldmask when you explicitly need per-grid-point data. For general analysis, use the ai_analysis field instead.

Fieldmasks work alongside other request parameters like placeId, keyword, and date filters. Filter first to narrow the result set, then apply a fieldmask to trim each result down to only the fields you need.

Next Steps