# Google Search Console

Proxy over the Search Console API. Search Analytics, Sites and Sitemaps use the
Webmasters v3 API (`www.googleapis.com/webmasters/v3`); URL Inspection uses
`searchconsole.googleapis.com/v1`. Read-only.

## Credentials

Same Google OAuth model as Analytics, token wins over service account:

| Header | Meaning |
| --- | --- |
| `X-GSC-Access-Token` | Ready OAuth2 access token (Bearer). |
| `X-GSC-Credentials` | Base64 service-account JSON; token minted with scope `https://www.googleapis.com/auth/webmasters.readonly`. |
| `X-GSC-Quota-Project` | Optional GCP project id → `x-goog-user-project`. |

The service account (or token's user) must be added to the property in Search
Console → **Settings → Users and permissions**.

## Site URL

Every endpoint takes the property as the `siteUrl` query parameter (the proxy
URL-encodes it into the upstream path):

- URL-prefix property: `https://example.com/`
- Domain property: `sc-domain:example.com`

## Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| POST | `/gsc/searchAnalytics/query?siteUrl=` | Search traffic (clicks, impressions, CTR, position). |
| GET | `/gsc/sites` | List sites in the account. |
| GET | `/gsc/site?siteUrl=` | Single site info + permission level. |
| GET | `/gsc/sitemaps?siteUrl=` | List submitted sitemaps. |
| GET | `/gsc/sitemap?siteUrl=&feedpath=` | One sitemap's details. |
| POST | `/gsc/urlInspection` | Index status of a URL (body has `inspectionUrl`, `siteUrl`, `languageCode`). |

### Search Analytics query body

```json
{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "dimensions": ["query", "page"],
  "rowLimit": 100
}
```

Forwarded unchanged; see
<https://developers.google.com/webmaster-tools/v1/searchanalytics/query>.

## Kde získat údaje (návod pro klienta)

1. Service account a base64 JSON klíč – viz hlavní popis ve Swaggeru / [google-analytics.md](google-analytics.md).
2. V [Search Console](https://search.google.com/search-console) → **Nastavení →
   Uživatelé a oprávnění** přidejte `client_email` service accountu.
3. `siteUrl` = adresa property tak, jak je uvedená v Search Console.

## Not wired (deliberately)

Writes — submitting/deleting sitemaps, adding/removing sites. They need the
`webmasters` (read-write) scope; add them if management is required.

## curl example

```bash
curl -X POST "https://services.csbot.cz/apps/analytics/gsc/searchAnalytics/query?siteUrl=https%3A%2F%2Fexample.com%2F" \
  -H "X-GSC-Access-Token: ya29...." -H "Content-Type: application/json" \
  -d '{"startDate":"2026-05-01","endDate":"2026-05-31","dimensions":["query"]}'
```