search a ads

2026-06-18 12:43:42 +02:00
parent 9cd5c8011b
commit 125b112967
12 changed files with 748 additions and 191 deletions
@@ -0,0 +1,71 @@
+# 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"]}'
+```