---
title: "Google Search Console API: make your first report"
description: "Make an authorized Search Console API request, read the returned metrics, and choose the right guide for filters, quotas, or hourly data."
canonical_url: "https://gscdump.com/learn-google-search-console/api"
last_updated: "2026-09-11"
---

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](/learn-google-search-console/api/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:

```bash
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](https://developers.google.com/webmaster-tools/v1/searchanalytics/query) 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](/learn-google-search-console/api/query-builder) walks through dimensions, filters, and pagination. For a recent traffic check, the [hourly API guide](/learn-google-search-console/api/hourly-search-analytics-api) explains incomplete-hour metadata.

## Choose the resource for the job

Google exposes different resources for different tasks. The [API reference](https://developers.google.com/webmaster-tools/v1/api_reference_index) 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](https://developers.google.com/webmaster-tools/v1/urlInspection.index/inspect) 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](/learn-google-search-console/limits/export-row-limits) before designing a complete-data archive.

If requests fail with quota errors, check [API rate limits](/learn-google-search-console/api/rate-limits). A costly query can hit a load limit even when your request count looks low.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.