Google Search Console API, BigQuery Export and Looker Studio: A Practical Guide

What the API gives you, and what it costs

The Search Console API gives programmatic access to the most popular reports and actions in your account. It returns performance data, sitemaps, property lists and URL inspection results, and it removes the 1,000-row limit of the interface. It covers four services: Search Analytics returns clicks, impressions, CTR and position; URL Inspection returns index status; Sitemaps and Sites manage submissions and properties. Each one mirrors a report in Search Console and inherits its rules. This guide also covers the bulk export to BigQuery and Looker Studio.

The price is easy. Google says "All use of Google Search Console API is free of charge. However, it is subject to usage limits" ^[1]. There is no paid tier for more data. The only costs come from what you build around it, such as a server or BigQuery storage for the bulk export. Data that sits behind a 1,000-row table in the interface becomes 50,000 rows a day per search type at no charge, limited mainly by how much code you are willing to write.

Access follows Search Console permissions. You need owner, full or read access to any property you want to reach, and a performance query needs read permission, so a restricted user can read data through the API. Writes need more. And if your site has fewer than 1,000 queries in the report table, the interface already shows everything. Export monthly, save the files, and build a pipeline only when tables start cutting rows.

Setting up access

Project, API and the first stumble

You need a Google account with Search Console access and a Google Cloud project, created in the Google API Console. The project holds quotas, credentials and billing if you later add BigQuery, and one project can serve many properties, so name it after the business, not after a person. Inside the project, open the API library, search for the Search Console API and enable it. If you forget, calls fail with accessNotConfigured. That error is the most common first stumble. It never means a permissions problem in Search Console itself.

OAuth or service account

Requests must be authorized with OAuth 2.0; no other protocol is supported. A simple rule works for most teams. If a person will run the analysis from a laptop or an AI assistant, use OAuth with that person's account. If a scheduled job will run every night, use a service account that belongs to the business, not to an employee. Decide early.

Scopes and the service account as a user

The webmasters scope gives read and write access, and webmasters.readonly gives read-only access. Adding sites and submitting sitemaps require the full scope, but for reporting, always request read-only. A leaked read-only token can expose data. It cannot change your properties. A service account is an email address like any other user, so add it in Search Console under Settings, then Users and permissions, with restricted or full access as needed. It counts toward the 100 non-owner limit. Remove it when the pipeline is retired.

Your first query with searchanalytics.query

To try the API without code, use the Try it! button on any method's reference page or the APIs Explorer. Start with a start date, an end date and the date dimension for the last ten days; the response shows which dates have data. Then add dimensions one at a time. When you move to code, Google's client libraries handle OAuth refresh and retries, which saves most of the boilerplate.

Search query data comes from searchanalytics.query, sent as a POST to the property's searchAnalytics endpoint ^[2]. It returns zero or more rows grouped by the dimensions you define, sorted by clicks, highest first, and a date range is required. The property address is where most first scripts fail. The siteUrl is the property exactly as Search Console defines it: the full prefix with protocol and trailing slash for a URL-prefix property, or sc-domain:example.com for a Domain property. Call sites.list first and copy the strings it returns, because guessing them is the most common cause of empty results.

Dates use YYYY-MM-DD in Pacific Time, and data is typically available after two to three days. Query a date three days back for complete data, which is exactly what Google's own pseudocode does. You can group by query, page, country, device, search appearance, date and hour. There is no limit on the number of dimensions, but you cannot group by the same one twice, and with no dimensions all values combine into a single row. The type parameter selects web, image, video, news, discover or googleNews. Web is the default and leaves out Discover and Google News, and the older searchType parameter is deprecated.

Filters, regex and aggregation

Filters can use any dimension, even one you do not group by. The operators are contains, equals, notContains, notEquals, includingRegex and excludingRegex. Equals is the default, and it is case-sensitive for page and query. Every filter group must match for a row to return, because groups combine with and only; or is not yet supported. The regex operators use RE2 syntax, the same flavor as the interface. To combine alternatives, put them inside one regex with a vertical bar rather than writing two filters that the API would join with and.

Aggregation is the other switch to understand. aggregationType can be auto, byPage or byProperty. If you group or filter by page, you cannot aggregate by property, and by page the data is aggregated by canonical URI. byProperty is not supported for discover or googleNews. The choice changes the totals you see. Set it explicitly.

How much data you can actually get

Paging up to the daily ceiling

rowLimit defaults to 1,000 and goes up to 25,000 per request. For bigger results, increase startRow by 25,000 until a call returns fewer rows than requested; a startRow past the end simply returns zero rows. The hard limit sits above that. The Search Analytics method exposes at most 50,000 rows per day per search type, sorted by clicks, so two pages of 25,000 rows exhaust it. A site with 60,000 page and query rows on one day therefore never gets 10,000 low-click rows from the API. Each extra dimension multiplies the rows, so grouping by date, page, query, country and device can easily pass the ceiling on a busy site.

Top rows, not all rows

The reference page is explicit: "The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones". Google's how-to page says the method exposes all data in the Performance report, but the reference page is the more precise statement, and grouping by page and query may drop data. Search appearance has its own quirk. It cannot be combined with any other dimension, so you first query it alone, then filter by one appearance type at a time. Five appearance types mean six calls.

Fresh data and hourly data

The dataState setting controls freshness. Final, the default, returns finalized data. All includes fresh data, some of which may be incomplete, and when grouped by date a first_incomplete_date field marks where values may still change. Use final for reporting. Mixing the two in one dashboard shows an artificial dip or spike at the boundary. Pick one state per report and label it. Since April 9, 2025, the API also offers hourly data for up to ten days, through an HOUR dimension and the hourly_all dataState, which is the one to use when grouping by hour. It suits launch monitoring. For trends, hourly data mostly adds noise.

Quotas, load and error codes

Search Analytics allows 1,200 queries per minute per site and per user, and 30,000,000 per day per project ^[3]. Other resources allow 20 per second and 200 per minute per user, and you can watch usage in the project's quota tab. Most sites never reach these numbers; a daily pipeline needs perhaps a dozen calls.

The limit people actually hit is the load quota, which measures the resources a query uses in 10-minute and one-day chunks. Queries grouped or filtered by both page and query are the most expensive, and a six-month range costs far more than a one-day range. If you exceed the short-term load quota, wait 15 minutes and try again. Spread queries through the day and avoid re-querying the same data. Query one day at a time. A job that pulls yesterday once and stores it never hits a limit, while a dashboard that asks for 16 months on every page load hits one quickly. When something does fail, the error code usually says why:

• 401 authError: invalid credentials.
• 403 accessNotConfigured: the API is not enabled in the project.
• 403 insufficientPermissions: the user lacks access to the property.
• 403 quotaExceeded or userRateLimitExceeded: a limit was reached.
• 429 rateLimitExceeded: too many requests in a given time span.

URL Inspection, sitemaps and sites

The inspection endpoint returns index status, AMP and rich result information for one URL. It reports only the version in the Google index, so you cannot test the indexability of a live URL, and it cannot request indexing. It allows 2,000 inspections per site per day. URL-prefix properties need the trailing slash in these calls. The sitemaps.submit method is a PUT request with the full webmasters scope and no request body, and a success returns an empty response body. The Sitemaps report notes that the API offers all the same functionality as the report itself.

sites.add is also a PUT request with the property URL and the full scope, and you can list and delete sites too. Adding a site through the API does not verify ownership. Agencies use sites.list to inventory every property a service account can see. The Indexing API is something else: it only serves pages with JobPosting or BroadcastEvent embedded in a VideoObject, and it is not part of the Search Console API.

Bulk data export to BigQuery

Bulk export schedules a daily export of your performance data to BigQuery ^[4], without the 50,000-row ceiling. It is the most complete query list Google offers and, unlike the interface, keeps data past 16 months, although anonymized queries arrive without their text. For a large store or publisher, every query and page combination for every day lands in tables you own.

Setting it up

Create or pick a Cloud project with billing, enable the BigQuery API and BigQuery Storage API, and grant search-console-data-export@system.gserviceaccount.com the BigQuery Job User and BigQuery Data Editor roles. Then in Search Console open Settings, then Bulk data export, and enter the project ID. The first export arrives within 48 hours, and after that Search Console exports once per day, with dates in Pacific Time. There is no backfill, so history before the start date has to come from the API.

Querying the tables

The export writes searchdata_site_impression, aggregated by property, and searchdata_url_impression, aggregated by URL, plus an ExportLog table. Data is not consolidated per key, so always aggregate fields with SUM, COUNT and similar functions; average position in the site table is SUM(sum_top_position)/SUM(impressions) + 1. Anonymized queries often make up the single most common query and appear as an empty string. Filter them out for query analysis, but keep them when you measure overall traffic, because their clicks still count. Copy Google's sample queries before writing your own.

Costs, retention and failures

Data is subject to Google Cloud storage and query costs, with a free usage level, and Google's Search Console pages publish no price list. A WHERE clause on the date partition cuts cost, and so does a daily summary table that dashboards read instead of the raw export. Data accumulates forever unless you set an expiration of 14 days or longer; never set one on the whole table, which deletes all your data. If an export fails, owners and full users get an email. Google retries a failed day for about a week, then drops it, and stops after about a month of failures.

Choosing your route, and the tools on top

Use the API for small and mid-sized sites, custom reports and anything that needs history before today. Use bulk export for large sites, full query lists and SQL. Many teams run both: the API once to pull the last 16 months, then bulk export for everything after. The interface keeps 16 months, and Google's traffic drop guide suggests pulling data through the API or the bulk export and storing it to extend that. Start now. Every month you wait, the oldest month disappears.

Looker Studio has a free Search Console connector and a Google template that puts clicks and CTR next to Analytics sessions and engagement. It is the fastest path to a shared dashboard, but it reads the same API with the same limits, so 16 months of query and page tables on every visit can still hit quota on a large site. Sheets add-ons and community MCP servers wrap the same API too. One Sheets add-on that SE Ranking describes stops at 5,000 rows, while ahonn's MCP server returns up to 25,000. Google publishes no official Search Console MCP server.

A daily pipeline that holds up

A sound pipeline is short. Authenticate with a service account key and build the client. Call searchanalytics.query with the site URL, a start and end date three days back, the page and query dimensions, a rowLimit of 25,000 and a startRow of 0, then repeat with startRow 25,000. Write each batch to a table keyed by date and log the row count. Google says a daily query for one day should not exceed your daily quota. Running at the same hour every day keeps each stored day final and comparable, and the row count shows gaps the morning after a failure.

Store keys outside code repositories, use read-only scopes, give each pipeline its own service account and review users twice a year. The common mistakes are predictable: a wrong siteUrl format, querying 16 months on every refresh, expecting anonymized queries, using fresh data for monthly reports, and forgetting the 50,000-row daily cap. Each produces numbers that look plausible and are wrong. Our Performance report guide explains the metrics the API returns, and the URL Inspection guide covers the interface version of the inspection endpoint.

The bottom line

The API turns Search Console from a 1,000-row dashboard into a data source: 50,000 rows a day per search type, hourly data and URL inspection, all free within quotas. It returns top rows, not every row, and Search Console keeps only 16 months, so start storing data now. Bulk export to BigQuery goes further for large sites and long history. Start with the API for history, add bulk export for the future, and use Looker Studio to share it.