Google Search Console API: Beginner’s Guide to Get Started

The Google Search Console is an essential tool for marketing teams that are concerned with search engine optimization (SEO). It allows you to see high-level data about your website’s visibility and traffic from Google and granular data for each page. Search Console can also help you understand your site’s performance in Core Web Vitals and manage your sitemap and content that is disallowed from Google.

While most non-technical users will be familiar with the visual web interface, Google Search Console also provides a powerful API that can help you gather more data, build internal tools, or integrate search data with your web application.

In this guide, we’ll explore the Search Console API in more detail by comparing it to the web interface, looking at some real-world use cases for it, and discussing its limitations. Finally, you’ll see exactly how to get started building an application that uses the Search Console API.

Features of the Google Search Console API

In order to better understand what’s possible using the Google Search Console API, let’s take a look at the services and methods available. You can read more about each of these in the documentation:

• Search Analytics - This service exposes a single endpoint allowing you to query search traffic data on your site. This is probably the most useful for building custom dashboards.
• Sitemaps - The four methods in this service allow you to list, retrieve, delete, or submit new sitemaps for your site.
• Sites - The Sites service lets you add, remove, retrieve, and list the sites you have in your Search Console. This might be useful if you’re building a tool that helps people manage many websites.
• URL Inspection - This service exposes an endpoint that gives you all the search data available for a single URL.

While most of the same underlying data is available through the API as in the web interface, the API is better suited to gathering the raw data, while the web interface is better for seeing a high-level overview of your site’s data. The API doesn’t include graphs or aggregate reports, but using the API and your own data store, you could generate custom reports or merge the Search Console data with other sources to provide richer insights to your team.

In the next section, we’ll explore some practical use cases for the Search Console API.

Practical Uses of the Google Search Console API for Marketers

Because Google commands such a large percentage of search engine market share, the data available in Google Search Console is a decent proxy for search engine performance of your site overall. Given this fact, you can use Search Console data in many ways to improve your understanding of your traffic, your SEO efforts, or your content marketing initiatives.

Search Performance Monitoring and Alerts

One way that SEOs could use the Search Console API is by setting up periodic pings to check if specific pages are ranking for or no longer ranking for specific keywords. This might be useful if you’re in a competitive field and want to retain your top result for high-value keywords.

Finding Opportunities for Search Engine Optimization

The web interface doesn’t make it easy to see the exact ranking of lots of specific pages over time, but using the API, you could build a tool that tracks keyword rankings for each page and how they change over time. This would allow you to build a tool that finds the best opportunities for optimizing or refreshing content that might be going stale or might have technical SEO issues.

Identifying and Resolving Sitemap Errors

If you have a large site that automatically generates sitemaps periodically, it can be hard to keep up with the changes and any errors they introduce. For example, e-commerce sites with thousands of product pages might have new products or variations come out, but a misspelled URL or novel URL structure could cause sitemap errors. The Search Console API could be used to programmatically check sitemaps every time they’re updated and ensure that you get alerts every time a breaking change is introduced.

Analyzing High CTR Content

Understanding which pages draw in the most clicks and their common attributes can be a good way to learn how search engines deliver your content to searchers and may show you opportunities to replicate this success. Unfortunately, the Search Console web interface filtering is pretty rudimentary, but the API will allow you to pull all your page data and give you more nuanced insights. For example, you could see how CTRs change across a subset of your pages over time after introducing a change (like new descriptions or titles).

Building or Enhancing SaaS Applications

If you’re building a software product for marketers, you might be able to use the Google Search Console API to enhance or improve your tool. For example, tools like Positional can use a Search Console API connection to give you more accurate data surrounding search terms and your placement in rankings.

This data is even more powerful when you can combine it with other data from your customers like page load time, A/B test criteria, or content updates. For example, if your application also pulled data from the customer’s CMS, you could understand the relationship between keyword rankings, the type or quality of content, and how often content is updated. The possibilities are endless.

Building Dashboards for Agency Clients

Finally, if you’re at a marketing or SEO agency, Search Console data could be a great way to offer your clients insights and show them the results of your work. Having run multiple agencies now, I can say that clients are much more likely to stick around when they know that what you’re offering them works.

While these use cases are by no means exhaustive, I hope this list gives you some insight into what’s possible with the Google Search Console API. That said, the Search Console API isn’t perfect, so let’s take a look at some of the limitations it has before we go further.

Limitations of the Google Search Console API

While some of these limitations won’t be relevant to your application, it’s helpful to understand what some of them are and how a developer might be able to work around them.

Query Results Size and Availability

The Google Search Console API limits query results to 50,000 rows per call, so if you’re pulling data from thousands of pages, you’ll need to batch these requests. But, because you can only make 1,200 queries per minute, your application will need to handle failed requests and back off.

Typically, the approach for handling jobs like this will involve a queue, but if you’re trying to process more queries than the API will let you handle, you may get a significant delay in your data availability.

Additionally, Google Search Console API data is not available in real-time. It typically takes 2-3 days for data to become available, so if you’re trying to get alerts on keyword changes, they won’t be up-to-the day correct.

Keyword Data Sampling

Much like in the Search Console web interface, the API’s keyword data is sampled, meaning it represents a subset of searches, and not every single Google search made. While you’ll never get perfect search data, you can augment the Google Search Console data with data from sources like Positional’s Keyword Tracking to get even closer to the truth.

Backlink Reporting Unavailable

The Google Search Console web interface has a “Links” report that can show you internal and external backlinks.

While this data can be manually exported from the user interface, it isn’t available in the Search Console API, so you can’t easily programmatically access it. Augmenting the Search Console data with data from other sources is probably the best way to work around this limitation.

While the Google Search Console API is a great resource, especially considering that it’s free, the gaps in this data and limited availability will make certain applications limited or impossible. That said, if you are looking to build something with the Search Console API, getting started is relatively easy. Let’s take a look at the process next.

Quick Tutorial to Get Started

In order to follow this section, you’ll need to have a basic understanding of Python programming, and have a suitable development environment set up. If you’re not a developer, you can spin up a remote environment quickly using an online IDE like Replit. You might also find a demo app like this onehelpful if you’re new to programming and want a way to get started quickly.

That said, if you’re experienced in working with Python and the Google API Authentication flow, you should be able to follow along and start building with the Google Search Console API.

1. Enable the Google Search Console API

First, you’ll need to log into your Google Account and then visit the Google Cloud Console. Assuming you haven’t already, create a Project for your new application.

Next, click “API & Services” in the Quick access menu and then “Credentials” on the left hand side menu. Click “Create Credentials” then “OAuth client ID” to begin the process of creating a new API key for your application. This key will allow you to programmatically access a user’s data from the Google Search Console API.

Select “Desktop app” and name it whatever you want.

Once created, download the JSON file and copy your Client ID and secret. Depending on how you build your application, you’ll either need to read the JSON file or add the Client ID and secret to your environment variables, so it’s good to have both.

Finally, before you leave the Google Cloud Console, go back to API & Services and click “Library” on the right hand menu. Search for and enable the “Google Search Console API” and “Indexing API” as these will allow your app to request data from these services.

2. Start a New Python Project

Now, you need to set up a new project and add your credentials to it. I’m using Python and Flask here, but the process is the same in any programming language supported by Google’s API Libraries.

import os
import flask
import requests

import google.oauth2.credentials
import google_auth_oauthlib.flow
import googleapiclient.discovery

Next, point your application to the JSON file containing your API credentials generated above, and set the access scopes using environment variables:

# Replace with your JSON file name
CLIENT_SECRETS_FILE = "client_secret.json"

SCOPES = ['https://www.googleapis.com/auth/webmasters.readonly']
API_SERVICE_NAME = 'searchconsole'
API_VERSION = 'v1'

app = flask.Flask(__name__)

# Replace this in production! See https://flask.palletsprojects.com/en/3.0.x/quickstart/#sessions
app.secret_key = 'REPLACE ME - this value is here as a placeholder.'

Finally, you can set up a home page and define the command for running Flask, which kicks off the web server and allows you to access this page from a web browser.‍

@app.route('/')
def index():
  return ('<table>' +
          '<tr><td><a href="/test">Test an API request</a></td>' +
          '<td>Submit an API request and see a formatted JSON response. ' +
          '    Go through the authorization flow if there are no stored ' +
          '    credentials for the user.</td></tr>' +
          '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' +
          '<td>Go directly to the authorization flow. If there are stored ' +
          '    credentials, you still might not be prompted to reauthorize ' +
          '    the application.</td></tr>' +
          '<tr><td><a href="/revoke">Revoke current credentials</a></td>' +
          '<td>Revoke the access token associated with the current user ' +
          '    session. After revoking credentials, if you go to the test ' +
          '    page, you should see an <code>invalid_grant</code> error.' +
          '</td></tr>' +
          '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' +
          '<td>Clear the access token currently stored in the user session. ' +
          '    After clearing the token, if you <a href="/test">test the ' +
          '    API request</a> again, you should go back to the auth flow.' +
          '</td></tr></table>')


if __name__ == '__main__':
  # When running locally, disable OAuthlib's HTTPs verification.
  # ACTION ITEM for developers:
  #     When running in production *do not* leave this option enabled.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  # Specify a hostname and port that are set as a valid redirect URI
  # for your API project in the Google API Console.
  app.run('localhost', 8080, debug=True)

You should be able to run this application from the command line assuming you have Flask installed:

$ flask –app main run

The output isn’t pretty, but it should look something like this:

Next, let’s complete the authentication flow and see how to actually start accessing data from the Google Search Console API.

3. Authenticate and Allow Access

All of Google’s APIs use OAuth 2.0 for authentication. While this standard is secure and widely used, it’s a bit complex. You can read up on how it works in Google’s developer documentation.

In order to create a valid OAuth flow in your application, you’ll need to copy the four routes described in Google’s OAuth 2.0 demo application:

• /authorize - Starts the authentication flow.
• /oauth2callback - Handles the authenticated user’s session credentials.
• /revoke - Revokes this application’s access to the user’s data.
• /clear - Removes the session credentials for this user.

Once you’ve copied those four routes from the demo application above, you’re ready to authorize a user and start accessing their data from the Search Console API.

4. Access Data Using the Python Client Library

Finally, add the following route to your main.py Flask application. This gets a list of sitemaps from the current user’s Google Search Console:

@app.route('/test')
def test_api_request():
    if 'credentials' not in flask.session:
        return flask.redirect('authorize')

    # Load credentials from the session.
    credentials = google.oauth2.credentials.Credentials(
        **flask.session['credentials'])

    # Retrieve list of properties in account
    search_console_service = googleapiclient.discovery.build(
        API_SERVICE_NAME, API_VERSION, credentials=credentials)
    site_list = search_console_service.sites().list().execute()

    # Filter for verified URL-prefix websites.
    verified_sites_urls = [
        s['siteUrl'] for s in site_list['siteEntry']
        if s['permissionLevel'] != 'siteUnverifiedUser'
        and s['siteUrl'].startswith('http')
    ]

    # Print the sitemaps for all websites that you can access.
    results = '<!DOCTYPE html><html><body><table><tr><th>Verified site</th><th>Sitemaps</th></tr>'
    for site_url in verified_sites_urls:

        # Retrieve list of sitemaps submitted
        sitemaps = search_console_service.sitemaps().list(
            siteUrl=site_url).execute()
        results += '<tr><td>%s</td>' % (site_url)

        # Add a row with the site and the list of sitemaps
        if 'sitemap' in sitemaps:
            sitemap_list = "<br />".join(
                [s['path'] for s in sitemaps['sitemap']])
        else:
            sitemap_list = "<i>None</i>"
        results += '<td>%s</td></tr>' % (sitemap_list)

    results += '</table></body></html>'

    # Save credentials back to session in case access token was refreshed.
    flask.session['credentials'] = credentials_to_dict(credentials)

    return results

The output should be a list of sitemaps submitted for each website you have access to in Google Search Console, so it should look something like this:

This simple example should get you started, but you can learn more about using the Search Console API in Python in Google’s API documentation.

Final Thoughts

Google Search Console is an important tool for anyone in content marketing to understand, but the web interface is just one way to gather insights from the tool. Using the API, SEOs and marketing teams can get more granular data and combine it with data from other tools to build an edge over their competition. You can use the Google Search Console API to build alerts, dashboards, or even SaaS products for marketers.

Finally, if you’re looking for even more insight - beyond just the Search Console - check out Positional. They offer a set of modern tools to analyze, optimize, and create better content and increase your chances of showing up at the top of search results. Get started with a free-trial or book a demo to learn more about Positional today.