Index of every page on this site: llms.txt
Skip to content

Branded search clicks by market with the Search Console API

Use one Search Analytics request to compare branded clicks across countries. Read the returned rows and handle a missing country without assuming zero clicks.

Harlan Wilton
4 min

If you report on several markets, you can compare branded Google Search clicks across countries in one Search Analytics request. Google added brand labels and filters for country lists to the API in November 2026.

Start with a complete week. In this example, you’ll count branded clicks from the United States, Canada, and the United Kingdom.

Request branded clicks for three countries

Use an eligible top-level Search Console property with enough query and impression data. Google documents branded API data from 21 February 2026. Check the API eligibility rules and the branded queries filter if you’re unsure whether your property qualifies.

You need Node.js 24 or later and a Google OAuth access token with the webmasters.readonly scope. Set GOOGLE_ACCESS_TOKEN in your shell before running the script. Follow the authentication guide to get a token and confirm property access.

Save the script as branded-clicks.mts.

import process from 'node:process'

const [property, startDate, endDate] = process.argv.slice(2)
const token = process.env.GOOGLE_ACCESS_TOKEN

if (!property || !startDate || !endDate || !token) {
  console.error('Set GOOGLE_ACCESS_TOKEN and pass a property, start date, and end date.')
  process.exit(1)
}

const response = await fetch(
  `https://www.googleapis.com/webmasters/v3/sites/${encodeURIComponent(property)}/searchAnalytics/query`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      startDate,
      endDate,
      type: 'web',
      dataState: 'final',
      dimensions: ['country'],
      dimensionFilterGroups: [{
        groupType: 'and',
        filters: [{ dimension: 'brandedClassification', operator: 'equals', expression: 'BRANDED' }],
        filterLists: [{ dimension: 'country', expressions: ['usa', 'can', 'gbr'] }],
      }],
    }),
  },
)

if (!response.ok)
  throw new Error(`Search Console returned HTTP ${response.status}.`)

const { rows = [] } = await response.json() as {
  rows?: { keys: [country: string], clicks: number }[]
}

if (rows.length === 0)
  console.log('Search Console returned no rows for this request.')
else
  console.table(rows.map(row => ({ country: row.keys[0], brandedClicks: row.clicks })))

Replace sc-domain:example.com with your property identifier. For a URL-prefix property, pass the full prefix as Search Console shows it. The script encodes either format in the request URL.

node branded-clicks.mts 'sc-domain:example.com' 2026-11-02 2026-11-08

Search Console includes both dates in Pacific Time. dataState: 'final' requests finalized data. If your date range includes recent days, check when they become available before comparing countries.

Read the country rows

filterLists keeps rows from any of the three countries. The brand filter also has to match. dimensions: ['country'] keeps the counts separate, so keys[0] gives the country code for each returned row. Leave out query filters when you group or filter by brandedClassification. See the request and response reference.

Suppose the script prints 420 clicks for usa and 95 for can. Those example counts cover the same week and search type. If gbr is missing, leave its value blank. The API can omit rows, and an ineligible property can return no rows at all.

To compare the same countries across weeks, change the dates and keep the property, search type, and country list fixed. To report non-branded clicks for the same week, change BRANDED to NON_BRANDED and run the request again.

To count all clicks from Google Lens, Circle to Search, and image uploads in these markets, send a separate request. Keep the country list, remove the brand filter, and set type: 'webMultimodal'. See Google’s multimodal reporting update.