Skip to content
MrKeyword
Developer

Google Search Console API: the developer guide

The Google Search Console API returns the same clicks, impressions, CTR and average position data as the Search Console Performance report, as JSON you can store and query. This guide covers OAuth, property URLs, dimensions, row limits, data delays, quotas and the official request examples, then compares the API with the Search Console UI and MrKeyword.

A search performance dashboard with charts of clicks and positions
The short version
  • The API is read-only for performance data: you call searchAnalytics/query with a date range and dimensions and get rows of clicks, impressions, CTR and average position.
  • Authenticate with OAuth 2.0 and the webmasters.readonly scope; use webmasters only if you also need to change sitemaps or sites.
  • A Domain property is addressed as sc-domain:example.com; a URL-prefix property as its full URL, such as https://www.example.com/.
  • rowLimit tops out at 25,000 rows per request (default 1,000); page with startRow and expect the API to return top rows, not every row.
  • Data lags by roughly two to three days, history covers 16 months, and quotas are 1,200 queries per minute per site and per user.

What is the Google Search Console API?

The Google Search Console API is a REST API that returns your Search Console performance data as JSON. You send a date range and a list of dimensions to the searchAnalytics/query method, and it returns rows of clicks, impressions, CTR and average position, grouped the way you asked. It is the same data behind the Performance report in the Search Console UI, exposed for scripts, dashboards and data warehouses.

The API is part of the Search Console API v3, formerly the Webmaster Tools API. It also lists your verified sites and manages sitemaps, but most developers use it for search analytics. Google's searchAnalytics/query reference is the authority for every field below.

How do you authenticate with OAuth 2.0?

Create a Google Cloud project, enable the Search Console API, configure an OAuth 2.0 client, and request the webmasters.readonly scope. The user signs in with the Google account that can access the Search Console property, and your app exchanges the authorization code for an access token.

  • Read-only scope: https://www.googleapis.com/auth/webmasters.readonly reads performance data, sites and sitemaps.
  • Read-write scope: https://www.googleapis.com/auth/webmasters also lets you add or remove sites and submit or delete sitemaps. Request it only when you need those writes.
  • Access tokens expire after about an hour. Store the refresh token and exchange it for a new access token instead of asking the user to sign in again.
  • Service accounts work only if the service account's email is added as a user on the Search Console property; a Domain property still needs that delegation.

Google's authorization guide covers the OAuth flow and the client libraries. Keep the client secret on the server, never in browser code.

Which property URL do you use?

Use the exact property identifier from Search Console: sc-domain:example.com for a Domain property, or the full URL for a URL-prefix property. The siteUrl path parameter must match the property as Search Console stores it, including the trailing slash on a URL-prefix property.

Property types and their API identifiers

Property typeCoverssiteUrl value
DomainEvery subdomain and protocol for the domainsc-domain:example.com
URL-prefixOnly URLs beneath the exact prefixhttps://www.example.com/
URL-prefix, subfolderOnly that folder and belowhttps://example.com/blog/
URL-encode the siteUrl when it appears in the request path. A Domain property and a URL-prefix property for the same site are separate data sets.

Call GET https://www.googleapis.com/webmasters/v3/sites to list the exact identifiers the authenticated account can read. Do not guess the form; copy it from that response.

Which dimensions and metrics can you query?

Group by any of query, page, country, device, date, searchAppearance and hour, and every row returns clicks, impressions, CTR and position. The order of the dimensions sets the order of the keys in each row.

Search Analytics dimensions and metrics

FieldTypeWhat it gives you
queryDimensionThe search query that produced an impression
pageDimensionThe URL that appeared in results
countryDimensionThree-letter ISO 3166-1 alpha-3 country code
deviceDimensionDESKTOP, MOBILE or TABLET
dateDimensionDay in YYYY-MM-DD, in Pacific time
searchAppearanceDimensionThe result feature, such as a rich result or video
clicksMetricClicks from Google search results to the property
impressionsMetricTimes a link to the property appeared
ctrMetricClicks divided by impressions, from 0 to 1
positionMetricAverage position for the row
You can filter by a dimension without grouping by it. Filters support equals, contains, notEquals, notContains, includingRegex and excludingRegex.

Use type to choose the surface: web (the default), image, video, news, discover or googleNews. Use aggregationType to aggregate by property or by page; if you group or filter by page, you cannot aggregate by property.

What are the row limits and how do you page?

rowLimit accepts 1 to 25,000 rows and defaults to 1,000; page through larger results with startRow. The API is bounded by Search Console's own limits and returns the top rows, not a guaranteed complete set. A query grouped or filtered by both page and query is the most expensive kind.

  • Default page size: 1,000 rows. Set rowLimit explicitly when you need more.
  • Maximum page size: 25,000 rows per request.
  • Paging: increase startRow by your page size until a response returns fewer rows than requested.
  • Sorting: results are sorted by clicks descending, or by date ascending when you group by date.
  • Missing days: when you group by date, days with no data are omitted, so do not assume a gap means zero.

How fresh is the data?

Search Console data lags by roughly two to three days, and the API keeps about 16 months of history. The most recent days can still change as Google finalises them. Request dataState: "all" to include fresh, incomplete data, or leave it at the default final for settled numbers.

When you request fresh data grouped by date, the response can include a metadata.first_incomplete_date field. Every date after it may still change noticeably, so treat those rows as provisional. For reporting, query final data and state the date range you used.

What are the quotas?

Search Analytics allows 1,200 queries per minute per site and 1,200 per user, with a per-project cap of 40,000 per minute and 30,000,000 per day. Google also enforces short-term and long-term load quotas that count how expensive a query is, not just how many you send.

Search Console API quotas, from Google's limits page

ResourceLimit
Search Analytics, per site1,200 queries per minute
Search Analytics, per user1,200 queries per minute
Search Analytics, per project40,000 per minute, 30,000,000 per day
URL inspection, per site600 per minute, 2,000 per day
All other resources, per user20 per second, 200 per minute
Queries grouped or filtered by page and query cost the most load. Spread them out and avoid re-querying the same range. See Google's usage limits.

If you exceed a quota you get a quotaExceeded error. Wait 15 minutes before retrying a short-term limit; if it still fails, you are over the long-term load quota and should reduce grouping, filtering or the date range.

Official request examples

Send a POST to the searchAnalytics/query method with a JSON body containing startDate, endDate and optional dimensions. These examples follow Google's reference; replace the placeholders with your own values.

List the properties you can read

GET https://www.googleapis.com/webmasters/v3/sites
Authorization: Bearer <access_token>
The response lists each property's siteUrl, permissionLevel and whether it is verified. Copy the siteUrl exactly.

Query clicks and impressions by country and device

POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "startDate": "2026-10-01",
  "endDate": "2026-10-31",
  "dimensions": ["country", "device"]
}
Google's own JSON POST example uses a date range and dimensions. The response returns rows sorted by clicks, each with keys, clicks, impressions, ctr and position.

Page through query rows with rowLimit and startRow

POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "startDate": "2026-10-01",
  "endDate": "2026-10-31",
  "dimensions": ["query"],
  "rowLimit": 25000,
  "startRow": 0
}
Increase startRow by 25,000 for the next page. Stop when a response returns fewer rows than rowLimit.

Filter to one page and include fresh data

POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "startDate": "2026-11-01",
  "endDate": "2026-11-14",
  "dimensions": ["query"],
  "dimensionFilterGroups": [
    {
      "filters": [
        { "dimension": "page", "operator": "equals", "expression": "https://www.example.com/pricing" }
      ]
    }
  ],
  "dataState": "all"
}
A URL-prefix property uses its full URL, URL-encoded in the path. dataState all includes fresh, still-changing data.

API vs Search Console UI vs MrKeyword

Use the API when you need the raw data in your own systems, the UI when you want to explore it by hand, and MrKeyword when you want the data stored, tracked and readable by AI tools without building an integration. Each covers a different job.

Google Search Console API compared with the UI and MrKeyword

CapabilitySearch Console APISearch Console UIMrKeyword
AccessOAuth 2.0, your own Google Cloud projectSign in to Search ConsoleConnect Search Console once, read-only
Data returnedJSON rows: clicks, impressions, CTR, positionCharts and tables you filter by handStored daily copy, plus Bing Webmaster Tools
HistoryAbout 16 months, same as the UIAbout 16 monthsBackfills up to 16 months, then keeps its own copy
Row limits25,000 per request, paged with startRowUI row caps per tableUp to 2,000 pages and 5,000 queries per site per day
EffortBuild and maintain the integrationNone, but manualNo code; MCP and API access included
Best forData warehouses, custom dashboards, automationQuick checks and one-off investigationsRank tracking, reporting and AI assistants
MrKeyword reads only your own verified sites. It does not add competitor or backlink data to Search Console data.

How do you get this data without building an integration?

Connect Search Console to MrKeyword and read the same data through its API or MCP server, with no Google Cloud project to maintain. MrKeyword syncs Search Console and Bing Webmaster Tools daily, stores its own copy, and exposes the data to dashboards and AI clients.

Skip the OAuth plumbing.Connect Search Console once and query the stored data from your own tools.

See the data API

Questions and answers

Google Search Console API questions

What is the Google Search Console API?

It is a REST API that returns your Search Console performance data as JSON. You call searchAnalytics/query with a date range and dimensions, and it returns rows of clicks, impressions, CTR and average position.

Which OAuth scope does the Search Console API need?

Use https://www.googleapis.com/auth/webmasters.readonly to read performance data, sites and sitemaps. Use https://www.googleapis.com/auth/webmasters only if you also need to add or remove sites or change sitemaps.

What is the row limit on the Search Console API?

rowLimit accepts 1 to 25,000 rows and defaults to 1,000. Page through larger results with startRow, and expect the API to return top rows rather than a guaranteed complete set.

How far back does the Search Console API go?

About 16 months, the same window as the Search Console UI. The most recent two to three days can still change as Google finalises them.

What are the Search Console API quotas?

Search Analytics allows 1,200 queries per minute per site and per user, with a per-project cap of 40,000 per minute and 30,000,000 per day. Google also enforces short-term and long-term load quotas.

Can I get Search Console data without building an API integration?

Yes. MrKeyword connects to Search Console read-only, syncs the data daily, stores its own copy and exposes it through its API and MCP server, so you skip the Google Cloud and OAuth setup.

About this article

Written by the MrKeyword team, who build an SEO workspace on first-party Search Console and Bing data. Outside facts link to their original source below. We update this page when the product or the sources change.

Sources

  1. Search Analytics query reference — Google for Developers: dimensions, rowLimit, startRow, dataState, scopes and the JSON POST example
  2. Search Console API usage limits — Google for Developers: 1,200 QPM per site and per user, project caps, URL inspection limits
  3. Authorizing requests — Google for Developers: OAuth 2.0 scopes
  4. Search Console performance data — Google Search Console Help: metrics, 16 months of data and delays
  5. MrKeyword developer reference — API and MCP endpoints, tokens, scopes and limits
Keep reading

More on MCP servers and APIs, plus the feature and free tool for the same job. All MCP servers and APIs guides →

Query Search Console data without the OAuth setup.

Connect Search Console to MrKeyword once and read the stored data through its API or MCP server. Free plan for one website, no card; paid plans from $10 a month.