---
title: "Query Google Search Console search analytics"
method: POST
path: "/v1/analytics/googlesearchconsole/search-analytics"
tags: ["Analytics"]
---

# Query Google Search Console search analytics

`POST /v1/analytics/googlesearchconsole/search-analytics`

## Request

- Base URL: `https://zernio.com/api`
- URL: `https://zernio.com/api/v1/analytics/googlesearchconsole/search-analytics`
- Auth: HTTP bearer

Clicks, impressions, CTR and average position from Google Search for a connected Search Console site, through Google's `searchAnalytics.query`.

Group by any of `date`, `hour`, `query`, `page`, `country`, `device`, `searchAppearance` and `brandedClassification`, and filter with Google's own filter groups. With no dimensions you get one row with the site's totals.

### Branded queries

`brandedClassification` splits searches into `BRANDED` and `NON_BRANDED`. Google has it from February 21, 2026, and only for sites with enough search volume. As a filter it takes `equals` only and cannot be combined with a `query` filter.

### Dates

Dates are `YYYY-MM-DD` in Pacific time. `toDate` defaults to yesterday and `fromDate` to 27 days before `toDate`, the window every report takes. Unknown fields answer 400. Google keeps 16 months, and the last two or three days are still filling in unless you pass `dataState: all`.

### Caching and quota

Identical requests on the same site are cached for 10 minutes. Google limits each site to 1,200 queries a minute; past it the request returns 429.

## Request body

- object
  - `accountId` string, required: Zernio account ID of the Google Search Console connection.
  - `fromDate` string, date
  - `toDate` string, date
  - `dimensions` string[]
  - `type` 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews' | 'webMultimodal': Which Google surface to read. Defaults to `web`. `webMultimodal` is Google Lens, Circle to Search and image uploads.
  - `dimensionFilterGroups` object[]
    - `groupType` 'and'
    - `filters` object[]
      - `dimension` 'query' | 'page' | 'country' | 'device' | 'searchAppearance' | 'brandedClassification', required: Narrow dates with fromDate and toDate instead.
      - `operator` 'equals' | 'notEquals' | 'contains' | 'notContains' | 'includingRegex' | 'excludingRegex': Defaults to `equals`.
      - `expression` string, required: The value to match. Countries are ISO 3166-1 alpha-3 codes (`usa`), devices `DESKTOP`, `MOBILE` or `TABLET`, brandedClassification `BRANDED` or `NON_BRANDED`.
    - `filterLists` object[]: Matches a row whose value is any of the expressions. A dimension goes in filters or in filterLists, not both.
      - `dimension` 'country' | 'device', required
      - `expressions` string[], required
  - `aggregationType` 'auto' | 'byPage' | 'byProperty' | 'byNewsShowcasePanel': byNewsShowcasePanel needs a NEWS_SHOWCASE searchAppearance filter and type discover or googleNews.
  - `rowLimit` integer: Defaults to 1000.
  - `startRow` integer: Row offset for paging past `rowLimit`.
  - `dataState` 'final' | 'all' | 'hourly_all': `final` (default) leaves out the last two or three days; `all` includes them while Google is still filling them in; `hourly_all` is required with the `hour` dimension.

## Response `200`

Rows from Google, ordered by clicks

- object
  - `data` object[]
    - `keys` string[]: One value per requested dimension in the same order. Absent when no dimensions were requested.
    - `clicks` number
    - `impressions` number
    - `ctr` number: Clicks divided by impressions, from 0 to 1.
    - `position` number: Average position in results (1 is the top).
  - `pagination` object
    - `hasMore` boolean: True when the page is full, so Google may hold more rows. Google does not say for sure.
    - `nextStartRow` integer, nullable: The startRow for the next page, or null when hasMore is false.
  - `meta` object
    - `accountId` string
    - `siteUrl` string
    - `fromDate` string, date
    - `toDate` string, date
    - `aggregationType` string, nullable
    - `firstIncompleteDate` string, date, nullable: From this Pacific day on the numbers can still change. Sent with dataState all when grouped by date.
    - `firstIncompleteHour` string, nullable: The same for hours, with dataState hourly_all when grouped by hour.

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired.
- `403`: The Google account that connected the site lost access to it in Search Console, or revoked Zernio. Reconnect Google Search Console.
- `404`: Resource not found
- `429`: The connected account's upstream platform quota is exhausted. Behavior per platform: - **Reddit:** rate-limits per connected Reddit user (1000 requests per 10-minute window), shared by every operation on that account. Retry after the window resets; repeated calls while exhausted do not succeed and keep the budget spent. - **Google Ads:** writes and reports run on one developer token shared by every Google Ads account on Zernio. It holds Standard access (no daily operations cap), so this only happens when Google throttles the token or your ad account. - **Google Ads envelope:** `code: rate_limited`, `platform: google`, `details.quotaScope: DEVELOPER` (`ACCOUNT` when it is your own ad account's quota), `details.resetsAt` (ISO instant when Google accepts requests again) and `Retry-After` counting down to it. Retrying earlier cannot succeed. - **YouTube Analytics:** reads (channel-insights, demographics, daily-views, video-retention) use the "Queries per day" quota of the Google Cloud project the account is connected through, shared with other Zernio customers, so a 429 is not your own volume. Resets at midnight Pacific Time. - **YouTube Analytics envelope:** `code: rate_limited`, `platform: google`, `details.quotaExhausted: true`, `details.quotaScope: DEVELOPER`, `details.resetsAt` and `Retry-After` counting down to it. Retrying earlier cannot succeed. - **Meta ads:** every Meta throttle (codes 4, 17, 32, 613 and business-use-case codes 80000-80014) returns 429 `rate_limited`, even when Meta answers HTTP 400. `Retry-After` comes from Meta's `x-business-use-case-usage` estimate when sent, else Meta's 60-second minimum (30 seconds for the one-write-per-30-seconds limit on one object). - **Pinterest ads:** limits per user and app, per category (ads_read, ads_write, ads_analytics). `Retry-After` comes from Pinterest's `x-ratelimit-reset` when sent, otherwise 60 seconds. - **TikTok ads:** limits per app and per endpoint (per second, minute and day), answering overage with code 40100 or code 40002 `OVER_QPS_LIMIT`. Both return 429 `rate_limited` with `platform: tiktok` and `Retry-After: 10`. Space out bulk reads (e.g. one ad at a time per advertiser) instead of retrying at once. **TikTok Smart+ review read** (`GET /v1/ads/{adId}/tiktok-smart-plus-review`) has its own stricter TikTok quota. After an overage, Zernio answers 429 for that advertiser and connection without calling TikTok for about 60 seconds, then 120, up to 240 while TikTok keeps refusing, each with up to 10% random jitter. A successful call holds nothing back; the next overage pauses about 60 seconds again. `Retry-After` is the time left. The advertiser-wide read (`GET /v1/ads/tiktok-smart-plus-reviews`) answers 200 with `retryAfterSeconds` and `refreshState` instead. Keep one request in flight per advertiser there.
- `502`: Google could not be reached, or failed while answering. Nothing was changed; retry shortly.

## Changes

- **2026-11-18** `d79b66285ac5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/analytics/googlesearchconsole/search-analytics/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/518557544cb4?raw)
