What is Google Search Console API and How to Use It?

Share this post

This post is part of the Guide on Google Search Console API

The Google Search Console API is a fantastic tool to help SEOs and webmasters query and backup all their search analytics data.

Google Search Console UI

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.

What Is the Google Search Console API?

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.

Try The API

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?

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

  • Search Analytics – lets you extract detailed information from the performance reports (Clicks, Impressions, CTR and Impressions).
  • Sitemaps – lets you list, add, remove or update sitemaps.
  • Sites – lets you get, list, add or delete website properties from GSC.

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: 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.