Google Search Console API

What the Google Search Console API Can Do

The Google Search Console API gives you programmatic access to the same data and actions available in the web interface. You can retrieve search performance metrics, manage site properties, submit sitemaps, and inspect URLs. This is useful for building custom dashboards and automating repetitive tasks.

The API offers four main services: Search Analytics, Sitemaps, Sites, and URL Inspection. Each service corresponds to a section of Search Console. The table below summarises their purposes.

To use the API, you need a Google account with the right permissions. For details on how how google search console works, see the main entry.

Search Analytics is the most heavily used service. You can query performance data filtered by date, query, page, country, device, and search appearance. The response includes clicks, impressions, CTR, and average position. You can also group results by up to two dimensions. For example, you can retrieve clicks per query for a specific country over the last 28 days.

Sitemaps lets you submit a sitemap URL, list all sitemaps for a property, and delete them. Each sitemap submission returns a status that you can check later. This is useful for large sites that add content frequently. The Sites service handles property management. You can add a new property, list all properties in your account, and remove them. Adding a property requires verification, which you can do via DNS, file upload, or other methods. URL Inspection returns crawl and index information for a single URL. It shows whether the page is indexed, the last crawl date, and any indexing errors. This is helpful for debugging why a page is not appearing in search results.

• Search Analytics: query performance data like clicks, impressions, CTR, and position.
• Sitemaps: submit, list, and delete sitemaps for your property.
• Sites: add, remove, or list properties in your account.
• URL Inspection: check the Google index status of a specific page.

How to Authenticate and Set Permissions

You authenticate with the Google Search Console API using OAuth 2.0. You need a Google account that has been granted access to the Search Console property you want to query. Permissions include owner, full user, and restricted user levels.

Without the correct permission, API calls will fail with authorisation errors. For example, a restricted user cannot add or remove properties. The API respects the same access controls as the web interface.

Unlike the bing search console API, which uses a different authentication model, Google's API relies on standard Google OAuth scopes. You must enable the Search Console API in the Google Cloud Console and create credentials.

Understanding Performance Data Queries

The Search Analytics service is the most commonly used part of the API. You can request data filtered by date range, query, country, device, and other dimensions. The API returns aggregated metrics like clicks, impressions, average CTR, and average position.

Google recommends querying one day of data at a time. This helps you stay within quota limits and makes it easier to handle data delays. Performance data is typically available after a delay of about 2-3 days, so near-real-time queries will show incomplete results.

When you query performance data, you are accessing data from Google Search itself. The API does not include data from other search engines. For a comparison with Bing's offering, see the entry on Bing Webmaster Tools.

• Dimensions you can filter by: date, query, page, country, device, search appearance.
• Metrics returned: clicks, impressions, CTR, position.
• You can group results by one or more dimensions.

Handling Search Appearance Data

Search appearance data (such as AMP, rich results, or video) requires a two-step querying approach. First, you query the API without any search appearance filter to get a list of appearances that have data. Then you query again with the specific appearance dimension.

You cannot combine search appearance with other dimensions in the first step. This is a known limitation. If you try, the API returns an error or incomplete data.

This behaviour reflects how Google's semantic understanding of content affects search results. For more on how Google interprets meaning, see how semantic search works.

The reason for the two-step process is that the API does not know which appearances are relevant for your property until you ask. For example, if your site has AMP pages and rich results, you first request a list of appearances that have data. The response might include "AMP" and "richResult". Then you query again with the dimension set to "AMP" to get metrics for that appearance. Alternatively, you can use the "searchAppearance" dimension in a single query, but only if you already know the appearance name. The API documentation warns that unknown appearances return empty results. So the two-step approach is safer and more reliable.

Managing Properties and Sitemaps via the API

The Sites service lets you add, remove, and list properties in your Search Console account. You can also verify ownership programmatically. The Sitemaps service allows you to submit new sitemaps, list existing ones, and delete them.

These actions are useful for automating site management across multiple properties. For example, you can add a new property and submit its sitemap in a single script.

For a similar capability on Bing, see how bing webmaster tools works. The Bing API offers comparable sitemap and site management features.

Adding a property via the API requires that you first verify ownership using one of the supported methods: DNS record, HTML file upload, Google Analytics tracking code, or Google Tag Manager. The API provides a verification status endpoint to check if verification succeeded. Once verified, you can submit sitemaps. The sitemap submission endpoint accepts a URL and returns a status object. You can also list all sitemaps for a property, which includes their submission date, crawl status, and error count. This is helpful for monitoring large sites with many sitemaps. For example, an e-commerce site with separate sitemaps for products, categories, and blog posts can automate the submission and check for crawl errors without logging into the web interface.

Common Quota and Delay Pitfalls

The API has daily quotas that limit the number of queries you can make. If you exceed the quota, you receive a 403 error. Google recommends querying one day of data at a time and caching results to avoid hitting limits.

Data delay is another common issue. Performance data is not real-time; it lags by 2-3 days. If you build a dashboard that expects today's data, it will appear incomplete. Plan your automation to account for this lag.

If you are building an internal search engine dashboard, you must handle these delays gracefully. The API is not suitable for real-time monitoring of search performance.

• Daily quota: depends on your project, but typically 2000 queries per day for Search Analytics.
• Data delay: performance data is 2-3 days behind.
• Search appearance queries require two steps, which counts as multiple queries.

Using the API for Automated Reporting and Dashboards

Many SEO professionals use the Google Search Console API to build automated reports and dashboards. You can pull daily performance data, track trends, and alert on drops in clicks or impressions.

The API is also useful for combining Search Console data with other sources, such as analytics or ranking tools. Because it returns structured data, you can store it in a database and query it historically.

Remember that the API data matches what you see in the Search Console web interface, but with the caveats of delay and quota. Always test your queries against the web interface to ensure accuracy.