Google Search Console API: make your first report

The Search Console API lets you put search performance into your own report. Start with one question: how many clicks did this property receive during a known period?

You need a Google account with access to the property and an OAuth access token. An ordinary Google API key cannot authorize access to this private data. If you don't have a token, start with authentication.

Request one period

This example asks for Web search totals for 1–7 September 2026. Replace the property and dates with your own. Both dates are included, using Pacific Time.

For a Domain property, use sc-domain:example.com. For a URL-prefix property, use its exact registered prefix, such as https://www.example.com/. Encode that whole value in the request URL.

With your access token already stored in the GOOGLE_ACCESS_TOKEN environment variable:

curl --fail-with-body \
  'https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query' \
  --header "Authorization: Bearer $GOOGLE_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "startDate": "2026-09-01",
    "endDate": "2026-09-07",
    "type": "web",
    "dataState": "final"
  }'

No dimensions means one aggregate row for the requested period, if data is available. Google's query reference documents the request and response.

Read clicks and impressions as counts. ctr is a fraction: 0.04 means 4%. position is an average across impressions, so it doesn't tell you where a page ranked every day. An empty response needs investigation; it doesn't establish that the property had no search activity.

Ask a more specific question

To see which pages received those clicks, add "dimensions": ["page"]. You'll get page rows instead of one property total.

That changes the meaning of the result. Detailed rows can omit information, and their sum may differ from an ungrouped total. Keep a separate totals request when your report needs both headline metrics and a page or query breakdown.

The query builder guide walks through dimensions, filters, and pagination. For a recent traffic check, the hourly API guide explains incomplete-hour metadata.

Choose the resource for the job

Google exposes different resources for different tasks. The API reference lists their methods.

Task	Resource	What to expect
Build a clicks or impressions report	Search Analytics	Aggregated performance rows
Check one URL's indexed status	URL Inspection	Information about Google's indexed version
Read or manage submitted sitemaps	Sitemaps	Sitemap submissions and related information
Find accessible properties	Sites	Properties available to the authorized account

URL Inspection cannot test the live page through this API. Its reference makes that distinction explicit.

Plan the next request

Pagination increases the rows returned across responses. It cannot restore query text Google withholds or overcome every internal data limit. Use the export limits guide before designing a complete-data archive.

If requests fail with quota errors, check API rate limits. A costly query can hit a load limit even when your request count looks low.