What is Google Search Console API?

The Google Search Console API is an application programming interface offered by Google to allow users to query the Google Search Console data without a user interface. Specifically, it is a partner API that can be used to extract search analytics data from the performance report, interact with site properties, sitemaps, and the URL inspection tool.

Even if Google drastically improved their tool in the last few years, Google imposes limitations to the amount of data they report to the user. In the search performance report, you can only see 1000 rows and can only get 16 months of historical data (used to be only 3 months of data).

The Google Search Console API, however, lets you extract that data.

This guide is part of the complete tutorial on the Google Search Console API.

What is Google Search Console?

Google Search Console (GSC), formerly Google Webmaster Tool (GWT), is the platform that Google offers to help monitor a website’s search performance. It provides tools that let webmasters test whether a page is indexed, how it is rendered and other traffic metrics like clicks, impressions, click-through-rate and position in Google.

Try The Google Search Console API

An API, or application programming interface, lets your interact with the data without the need for the user interface.

You can try the GSC API in your browser the API Explorer.

You will see a panel on the right side.

From that page, you can make a request to your Search Analytics Data from that interface and process the response.

What Information Can You Extract From GSC API?

The Google Search Console API has three functionalities: search analytics, sitemaps and sites.

Search Analytics – Extract detailed information from the performance reports (Clicks, Impressions, CTR and Impressions).
Sitemaps – List, add, remove or update sitemaps.
Sites – Get, list, add or delete website properties from GSC.
URL Inspection – Inspect indexation status of a page in Google Index

Search Analytics

With the search analytics You can extract up to 25,000 rows per requests. For most websites, this is enough to backup all their search analytics data. For others, options are available to query all your search analytics data.

The data you can query is the same as what you would see in the GSC user interface.

The Search console api dimensions that you can query are: date, page, query, searchAppearance, device and country.

For each of those dimensions, you can extract clicks, impressions, click-through-rate (CTR) and position.

Basic Request Syntax

The required elements you need to add to a Google Search Console API request are the startDate, the endDate and the dimension.

startDate must be in the format YYYY-MM-DD
endDate should end at least 3 days in the past since GSC don’t properly report the last three days.
dimension has one of the following values: page, query, country, device, searchAppearance

Other optional elements you can add are dimensionFilterGroups, aggregationType and searchType.

Here is an example of a basic simple query.

{
  "startDate": "2020-05-01",
  "endDate": "2020-05-05",
  "dimensions": [
    "page",
    "query"
  ]
}

Google Search Console API Dimensions

page: Filters by URI strings.
query: Filters by queries (also known as keywords)
country: Filters by ISO country
device: Filters by device type:
- DESKTOP
- MOBILE
- TABLET
searchAppearance: Filters by search result featureAMP_BLUE_LINK
- INSTANT_APP
- RICHCARD
- JOB_LISTING
- JOB_DETAILS
- TPF_FAQ
- REVIEW_SNIPPET

Filter Data With Optional Expressions

DimensionFilterGroups

Using dimensionFilterGroups, you can filter your data to extract only specific information.

Use operators to filter the data. The accepted values are contains, equals, notContains, notEquals.

Use groupType if you want to use the and operator.

aggregationType

Using aggregationType you can group data byPage to aggregate values by URI or byProperty to aggregate values by property.

searchType

Using searchType, you can extract image, video or web search results (default).

startRow and rowLimit

Using startRow and rowLimit you can send batch requests to query all your Search Analytics data.

Simple example using filters

This example will query all the pages containing python-for-seo in the URI between may 1st and may 5th.

{
  "startDate": "2020-05-01",
  "endDate": "2020-05-05",
  "dimensions": [
    "date",
    "page",
    "query"
  ],
  "dimensionFilterGroups": [
    {
      "filters": [
        {
          "dimension": "page",
          "operator": "contains",
          "expression": "python-for-seo"
        }
      ]
    }
  ]
}

Advanced example using filters

This sample will extract all pages that rank for queries that contain python and seo and aggregate the results by page.

{
  "startDate": "2020-05-01",
  "endDate": "2020-05-05",
  "dimensions": [
    "date",
    "page",
    "query"
  ],
  "dimensionFilterGroups": [
    {
      "filters": [
        {
          "dimension": "query",
          "operator": "contains",
          "expression": "python"
        },
        {
          "dimension": "query",
          "operator": "contains",
          "expression": "seo"
        }
      ]
    },
    {
      "groupType": "and"
    }
  ],
  "aggregationType": "byPage"
}

Extract Google Search Console data with Python

Congratulations. You now understand how to query the Google Search Console API.

We will now learn how to query the Google Search Console API using Python.

4/5 - (1 vote)

Jean-Christophe Chouinard

SEO Strategist at Tripadvisor, ex- Seek (Melbourne, Australia). Specialized in technical SEO. Writer in Python, Information Retrieval, SEO and machine learning. Guest author at SearchEngineJournal, SearchEngineLand and OnCrawl.