# Reports

Query Google Search clicks, impressions, CTR and position for a connected site, list its sitemaps and inspect a URL's index status.

Every call takes the `accountId` of a connected Google Search Console account. Zernio passes the request to Google's Search Console API and returns Google's data, with `accountId` and `siteUrl` added.

## Query search analytics

Group by up to eight dimensions and get clicks, impressions, CTR and average position for each row:

```bash
curl -X POST "https://zernio.com/api/v1/analytics/googlesearchconsole/search-analytics" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "ACCOUNT_ID",
    "fromDate": "2026-10-01",
    "toDate": "2026-10-31",
    "dimensions": ["query"],
    "rowLimit": 50
  }'
```

```json
{
  "data": [
    { "keys": ["social media api"], "clicks": 412, "impressions": 9875, "ctr": 0.0417, "position": 6.3 }
  ],
  "pagination": { "hasMore": false, "nextStartRow": null },
  "meta": {
    "accountId": "ACCOUNT_ID",
    "siteUrl": "sc-domain:acme.com",
    "fromDate": "2026-10-01",
    "toDate": "2026-10-31",
    "aggregationType": "byProperty"
  }
}
```

Rows come ordered by clicks. `keys` holds one value per dimension, in the order you asked for them. With no dimensions you get one row with the site's totals and no `keys`.

A full page sets `pagination.hasMore`, and `nextStartRow` is the `startRow` for the next one. Google does not say whether more rows exist, so the last page can come back empty.

`ctr` runs from 0 to 1, and `position` is the average position in results, where 1 is the top.

## Request fields

| Field | What it does |
|-------|--------------|
| `fromDate`, `toDate` | `YYYY-MM-DD` in Pacific time. `toDate` defaults to yesterday and `fromDate` to 27 days before `toDate`, so 28 days in all. Google keeps 16 months. |
| `dimensions` | Any of `date`, `hour`, `query`, `page`, `country`, `device`, `searchAppearance` and `brandedClassification`. |
| `type` | The Google surface to read: `web` (default), `image`, `video`, `news`, `discover`, `googleNews` or `webMultimodal` (Google Lens, Circle to Search and image uploads). |
| `dimensionFilterGroups` | Up to 5 groups. Each holds `filters` (a `dimension`, an `operator`, default `equals`, and an `expression`) and `filterLists` (`country` or `device` with several `expressions`, any of which matches). |
| `aggregationType` | `auto`, `byPage`, `byProperty` or `byNewsShowcasePanel` (with a `NEWS_SHOWCASE` search appearance filter on `discover` or `googleNews`). |
| `rowLimit`, `startRow` | Rows per page (1 to 25,000, default 1,000) and the row to start from. Page with `startRow` until a page comes back short. |
| `dataState` | `final` (default) leaves out the last two or three days, which are still filling in. `all` includes them. `hourly_all` is required with the `hour` dimension. |

Countries in filters are ISO 3166-1 alpha-3 codes such as `usa`, and devices are `DESKTOP`, `MOBILE` or `TABLET`. Operators are `equals`, `notEquals`, `contains`, `notContains`, `includingRegex` and `excludingRegex`.

For example, the top pages from mobile searches in the United States:

```bash
curl -X POST "https://zernio.com/api/v1/analytics/googlesearchconsole/search-analytics" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "ACCOUNT_ID",
    "dimensions": ["page"],
    "dimensionFilterGroups": [{ "filters": [
      { "dimension": "country", "expression": "usa" },
      { "dimension": "device", "expression": "MOBILE" }
    ] }],
    "rowLimit": 20
  }'
```

### Branded and non-branded searches

Group by `brandedClassification` to split clicks between searches for your brand and the rest. This example covers three countries:

```bash
curl -X POST "https://zernio.com/api/v1/analytics/googlesearchconsole/search-analytics" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "ACCOUNT_ID",
    "dimensions": ["brandedClassification"],
    "dimensionFilterGroups": [{ "filterLists": [
      { "dimension": "country", "expressions": ["usa", "gbr", "can"] }
    ] }]
  }'
```

Google has the split from February 21, 2026, and only for sites with enough search volume. As a filter it takes `equals` with `BRANDED` or `NON_BRANDED`, and never sits beside a `query` filter.

With `dataState: all` and grouped by `date`, `meta.firstIncompleteDate` names the first day whose numbers can still change.

Filters and fields follow Google's [searchAnalytics.query](https://developers.google.com/webmaster-tools/v1/searchanalytics/query) reference.

## List sitemaps

Call `GET /v1/analytics/googlesearchconsole/sitemaps` to see the sitemaps submitted for the site, when Google last read them, their errors and warnings and how many URLs each holds:

```bash
curl "https://zernio.com/api/v1/analytics/googlesearchconsole/sitemaps?accountId=ACCOUNT_ID" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```

```json
{
  "meta": { "accountId": "ACCOUNT_ID", "siteUrl": "sc-domain:acme.com" },
  "data": [
    {
      "path": "https://acme.com/sitemap.xml",
      "lastSubmitted": "2026-10-28T09:12:00Z",
      "lastDownloaded": "2026-11-17T04:31:00Z",
      "isPending": false,
      "isSitemapsIndex": false,
      "type": "sitemap",
      "warnings": "0",
      "errors": "0",
      "contents": [{ "type": "web", "submitted": "1250" }]
    }
  ]
}
```

Counts such as `warnings`, `errors` and `submitted` are strings, as Google sends them.

## Inspect a URL

Call `POST /v1/analytics/googlesearchconsole/url-inspection` with a URL of the connected site to see whether Google has indexed it, its canonical, last crawl, robots and fetch state, mobile usability and rich results:

```bash
curl -X POST "https://zernio.com/api/v1/analytics/googlesearchconsole/url-inspection" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accountId": "ACCOUNT_ID", "inspectionUrl": "https://acme.com/pricing" }'
```

```json
{
  "data": {
    "inspectionUrl": "https://acme.com/pricing",
    "result": {
      "inspectionResultLink": "https://search.google.com/search-console/inspect?…",
      "indexStatusResult": { "verdict": "PASS", "coverageState": "Submitted and indexed", "lastCrawlTime": "2026-11-15T22:04:11Z", "googleCanonical": "https://acme.com/pricing" }
    }
  },
  "meta": { "accountId": "ACCOUNT_ID", "siteUrl": "sc-domain:acme.com" }
}
```

`data.result` is Google's own object, and each part is present only when Google has it. Pass `languageCode`, such as `en-US`, for issue messages in another language.

## How it behaves

- Identical search analytics and sitemap requests on the same site are cached for 10 minutes. URL inspections are cached for 1 hour.
- Google limits search analytics to 1,200 queries a minute per site.
- Google allows 2,000 URL inspections a day and 600 a minute per site. A cached inspection does not count.
- Search data settles over two or three days, and Google refreshes it about once a day.
- The dashboard shows the same data under Analytics > Website: clicks, impressions, CTR, average position, a daily chart and the top queries, pages, countries and devices.

## If it fails

| Error | Cause | Fix |
|-------|-------|-----|
| `400` | A field is invalid, or Google rejected a date, filter or URL; the message names it | Fix the field. An inspected URL must belong to the connected site. |
| `403` | The account is disconnected, or the Google account lost access to the site or removed Zernio | Reconnect Google Search Console. |
| `404` | The account does not exist, is not a Google Search Console account, or your key cannot reach it | List your accounts with `GET /v1/accounts?category=analytics`. |
| `429` with `rate_limited` | Google's quota for the site is used up | Retry after the quota refills, and reuse cached requests where you can. |

## Related

- [Query search analytics](/analytics/query-google-search-console-search-analytics)
- [List sitemaps](/analytics/list-google-search-console-sitemaps)
- [Inspect a URL](/analytics/inspect-google-search-console-url)
- [Connect](/platforms/google-search-console/connect)