How do I set up a repeatable multi-location Google Business Profile Performance API export?

What should I save for each export?

Treat the export as five linked records. The data file is not complete without the request manifest that explains its scope.

Keep the raw response as well as any reporting table. A normalized table can make comparisons easier, but it must not erase whether Google omitted a zero daily value or returned a monthly threshold.

How do I authenticate and enumerate all accessible locations?

Use one OAuth authorization with the scope below, then build the manifest in two paginated passes.

https://www.googleapis.com/auth/business.manage

1. Call accounts.list for the authenticated user.
2. Store every account returned, and call again with the returned pageToken until nextPageToken is absent. Google says this list includes accounts the user owns and accounts where the user has management rights. The personal account is first unless it is filtered out.²
3. For each account, call accounts.locations.list with a readMask. Set pageSize between 1 and 100; the default is 10.
4. Follow the location list's nextPageToken until it is absent. Do not treat the first response as the full location set.³
5. Keep the returned location resource in the form locations/{locationId}. The Performance API expects an unobfuscated listing ID in that resource name. If your system starts with another identifier, verify its mapping before calling the Performance API.^1,3

The account type changes what the location list can return. For a PERSONAL account, Google returns only locations directly owned by that account. Other account types return all locations accessible through that account, directly or indirectly.³ Keep the account that produced each manifest row so the same location is not silently attributed to the wrong account when you reconcile multiple pages.

Which daily metrics should I request?

Choose the daily enums your report needs, and keep the enum names beside the result. The current Performance reference documents these metric families:

Google marks BUSINESS_CONVERSATIONS and BUSINESS_FOOD_ORDERS as deprecated in the same enum reference.⁴ Keep those labels visible if an old configuration still requests them, but do not add deprecated enums to a new default metric set without rechecking Google's current documentation.⁴

For reader-facing definitions of Views, Searches, calls, directions, bookings, and menu activity, use the Google Business Profile performance metrics guide. The API enum and the owner-facing report label are not always the same thing,^4,5 so preserve both when your reporting layer maps one to the other.

How do I fetch daily data for every location?

Call locations.fetchMultiDailyMetricsTimeSeries once for each selected location. The method accepts repeated dailyMetrics query values, requires a dailyRange, and uses an empty request body. Its path contains one locations/* resource, so the loop over the manifest is what makes the export multi-location.¹

If a separate job needs only one daily metric for a location, Google's locations.getDailyMetricsTimeSeries method is the single-metric alternative. Keep the same location resource and inclusive date-range record.⁶

For each location, persist these request fields before accepting the response:

location: locations/{unobfuscatedLocationId}
dailyMetrics[]: [the exact enum names requested]
dailyRange.startDate: YYYY-MM-DD
dailyRange.endDate: YYYY-MM-DD
requestBody: empty

Both startDate and endDate are inclusive. Store them next to every time series, not only in a job-level configuration, because the date range is part of what the value means.^1,4

The response contains a metric, an optional dailySubEntityType, and a time series of date-value pairs. Google says the value field is not present when the value is zero.⁴ Normalize that deliberately:

• value present: store the returned integer.
• value absent in a returned date-value pair: store 0 with a state such as omitted_zero.
• The metric or response is absent because the request failed or the response is incomplete: store an error or incomplete state, not zero.
• dailySubEntityType absent: keep it absent. Do not invent a breakdown.

This distinction protects the export from turning a valid zero into an unknown value or turning an incomplete response into a false zero.

How do I export monthly search keywords?

Run locations.searchkeywords.impressions.monthly.list separately for each location. Use the same locations/{locationId} resource from the manifest, set an inclusive startMonth and endMonth, and continue with nextPageToken until no token remains.³

The monthly range is month-granular. Google considers only the year and month fields, not a day within the month. pageSize defaults to 100 and cannot exceed 100.³

Store each keyword row with these fields:

insightsValue is a union. It contains either the sum of unique users who used the keyword across the requested months or a threshold below which the actual value falls.³ A threshold is not an exact count. Keep the union arm in the file and render a threshold as “below [threshold]” rather than as that number.

How do I validate the file before I accept it?

Run these checks in order. The first failed check identifies what to repair before a comparison or dashboard consumes the file.

Google says Performance data is available only for verified Business Profiles, requires the associated Google Account, and shows only metrics that apply to the business. Google also says the Searches metric updates at the start of each month and can take up to 5 days to appear.⁵

Can I use Google's manual download as a cross-check?

Yes. Use it as a control check for profile selection and timeframe, not as proof that the spreadsheet and API response have identical columns or semantics.

In Business Profile Manager on a computer:

1. Select the checkbox beside the profiles to compare.
2. At the top right, click Actions, then Insights.
3. Select the timeframe.
4. Click Download Report.⁵

Save the selected profiles, timeframe, and downloaded filename beside the API export. Compare the profile set and date or month scope first. Keep the API's daily zero-omission state, monthly value versus threshold, and exact location resource names in the API record even when the manual file presents a different layout.