google search consolegsc apiapiautomationkeyword researchseo toolsdata

Google Search Console API: Complete Guide (What It Is, How to Use It)

Learn what the Google Search Console API is, how to authenticate and query it, what data you can pull, and when to use the API vs a tool like Search Console Tools.

Search Console Tools Team••8 min read
Table of Contents

Google Search Console API: Complete Guide

The Google Search Console API gives you programmatic access to the same data you see in the GSC dashboard — impressions, clicks, CTR, average position, coverage status, and more. Instead of manually exporting CSVs or navigating the UI, you can query this data directly from code or third-party tools.

If you've ever hit GSC's row limits, wanted to schedule automated reports, or tried to combine GSC data with other sources (GA4, Sheets, your own database), the API is what unlocks that.

This guide covers everything: what the API provides, how authentication works, what you can query, real use cases, and when it's worth the setup vs using a tool that already handles the API for you.

What Is the Google Search Console API?

The Google Search Console API (also called the Search Analytics API) is a REST API that lets you:

  • Query your site's search performance data (queries, pages, countries, devices, dates)
  • Check URL indexing status and crawl errors
  • Submit URLs for re-indexing (via the Indexing API, a related but separate API)
  • Access sitemap data (submit, list, delete sitemaps)
  • Retrieve structured data enhancement reports

The most commonly used endpoint is the Search Analytics query endpoint, which mirrors what you see in GSC's Performance report — but without row limits, with full programmatic control, and with the ability to automate.

Google Search Console API vs. Manual GSC

| Feature | GSC Dashboard | GSC API | |---------|---------------|---------| | Row limit | 1,000 rows (UI), 25,000 per query (export) | 25,000 per request; paginate for more | | Date range | Up to 16 months | Up to 16 months | | Automation | Manual only | Fully automatable | | Scheduling | None | Run on cron/schedule | | Data blending | No | Combine with any data source | | Skill required | None | API/coding knowledge or a tool |

When to use the API: Large sites (1,000+ pages), agencies managing multiple properties, developers building SEO tools, anyone who needs scheduled reports or data pipelines.

When the UI is enough: Sites under a few hundred pages, quick one-off analysis, users who don't code.

Authentication: How to Access the GSC API

The GSC API uses OAuth 2.0 for authentication. There are two main approaches:

Best for server-to-server access, cron jobs, and production pipelines.

  1. Go to Google Cloud Console
  2. Create a new project (or use an existing one)
  3. Enable the Google Search Console API under APIs & Services
  4. Create a Service Account under IAM & Admin
  5. Download the JSON key file
  6. In Google Search Console, add the service account email as a verified owner or full user of your property

Option 2: OAuth 2.0 User Flow

Best for tools or apps where users authenticate with their own Google accounts.

  1. Create OAuth 2.0 credentials in Google Cloud Console
  2. Set redirect URIs for your application
  3. Implement the OAuth flow to obtain an access token
  4. Use the access token in API requests

For most automation use cases, service accounts are simpler — no browser interaction required once set up.

The Search Analytics API: What You Can Query

The core endpoint is:

POST https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query

Dimensions

You can break data down by any combination of:

  • query — search queries (keywords)
  • page — landing page URLs
  • country — user country
  • device — desktop, mobile, tablet
  • date — individual dates
  • searchAppearance — rich results, AMP, etc.

Metrics

For each dimension combination, you get:

  • clicks — number of clicks
  • impressions — number of impressions
  • ctr — click-through rate
  • position — average ranking position

Filters

You can filter by any dimension before aggregating. For example:

  • Only queries containing a specific keyword
  • Only pages matching a URL pattern
  • Only mobile device traffic

Date Ranges

Specify startDate and endDate in YYYY-MM-DD format. Data goes back up to 16 months.

Sample API Request (Python)

Here's a minimal example pulling top 10 queries for a site over the last 28 days:

from googleapiclient.discovery import build
from google.oauth2 import service_account

# Authenticate with service account
SCOPES = ['https://www.googleapis.com/auth/webmasters.readonly']
credentials = service_account.Credentials.from_service_account_file(
    'service-account-key.json', scopes=SCOPES
)
service = build('searchconsole', 'v1', credentials=credentials)

# Query the API
request = {
    'startDate': '2026-01-26',
    'endDate': '2026-02-23',
    'dimensions': ['query'],
    'rowLimit': 10,
    'startRow': 0
}

response = service.searchanalytics().query(
    siteUrl='https://yoursite.com',
    body=request
).execute()

for row in response.get('rows', []):
    print(row['keys'][0], row['clicks'], row['impressions'], row['ctr'], row['position'])

This returns the top 10 queries by impression count for your site over the specified date range.

Common GSC API Use Cases

1. Automated Keyword Performance Reports

Schedule a daily or weekly script to pull your top 50 queries, track position changes over time, and email a summary. This gives you historical position tracking without paying for a rank tracker.

2. Find Striking Distance Keywords at Scale

Programmatically pull all queries where position is between 4 and 20 and impressions > 100. These are your highest-priority optimization targets. On large sites, there can be hundreds of these — impossible to find manually in the UI.

3. CTR Analysis by Landing Page

Pull data by page dimension and calculate each page's actual CTR vs. the expected CTR for its average position. Pages underperforming their position benchmark have title or description issues worth fixing.

4. Multi-Site Dashboard

If you manage multiple GSC properties, the API lets you pull data from all of them into a single database or spreadsheet. Compare performance across sites, identify winning patterns, and catch declining properties early.

5. Integration with GA4

Combine GSC clicks and impressions with GA4 sessions and conversions. Identify which search queries drive your most valuable traffic — not just the most clicks.

6. Content Decay Detection

Programmatically compare current performance vs. 90 days ago for every page on your site. Pages where impressions have dropped >30% are candidates for a content refresh.

API Limits and Quotas

  • Queries per day: 200 requests per 100 seconds per project (adjustable with quota increases)
  • Rows per request: Up to 25,000
  • Date range: Up to 16 months of data
  • Properties per account: Limited by your GSC verified properties
  • Sampling: Data for smaller sites may be sampled at very high row counts

For most SEO use cases, default quotas are more than sufficient.

When to Use the API vs. a Tool

The API is powerful but requires setup, maintenance, and coding knowledge. Search Console Tools (searchconsoletools.com) is built on top of the GSC API and handles authentication, querying, and analysis for you — no code required.

Use the raw API when:

  • You're building a custom internal tool or data pipeline
  • You need to combine GSC data with proprietary data sources
  • You want full control over data storage and processing
  • You have engineering resources to build and maintain the integration

Use Search Console Tools when:

  • You want striking distance analysis, CTR benchmarking, and content decay detection without writing code
  • You're managing 1–50 sites and need fast answers
  • You want automated reports in a clean interface
  • You want the API's power without the API's complexity

FAQ

Do I need to pay for the Google Search Console API? No. The GSC API itself is free. You pay for Google Cloud (for the OAuth/service account infrastructure), but costs are negligible for typical SEO use — usually under $1/month or free under GCP's free tier.

Can I use the GSC API to submit URLs for indexing? Not directly. URL submission uses the separate Indexing API, which is also free. The two APIs are different — the Search Analytics API reads performance data; the Indexing API notifies Google of URL changes.

How far back does GSC API data go? Up to 16 months. This matches what's available in the GSC dashboard. Data older than 16 months is not accessible through any method.

How many rows can I pull at once? Up to 25,000 rows per request. For sites with more queries than that, use startRow to paginate through the full dataset.

What's the difference between the GSC API and the Search Console API? They're the same thing. "Google Search Console API" and "Search Console API" and "Search Analytics API" all refer to the same set of endpoints under googleapis.com/webmasters/v3.

Can I pull GSC data into Google Sheets? Yes — Google Sheets has a built-in Google Analytics connector that includes limited GSC data, but for full control, use the API with Google Apps Script or a Sheets add-on like Supermetrics or Search Analytics for Sheets.

Put These Tips Into Action

Connect your Google Search Console and let our AI find your biggest opportunities.

Get Started Free