# Google Ads

Proxy over the Google Ads API `GoogleAdsService` (GAQL search / searchStream),
which covers virtually all Google Ads reporting. Bodies are forwarded as-is.

The API version is in an env var (`GOOGLE_ADS_API_VERSION`, default `v19`)
because Google deprecates versions roughly yearly — bump it without a code
change. Base URL: `https://googleads.googleapis.com/{version}`.

## Credentials

Google Ads needs more than a Bearer token:

| Header | Required | Meaning |
| --- | --- | --- |
| `X-GAds-Developer-Token` | **yes** | Developer token from a Google Ads manager account → `developer-token`. |
| `X-GAds-Access-Token` | one of these | Ready OAuth2 access token (Bearer). |
| `X-GAds-Credentials` | one of these | Base64 service-account JSON (scope `adwords`); needs domain-wide delegation. |
| `X-GAds-Login-Customer-Id` | no | Manager (MCC) id → `login-customer-id`. Digits only. |
| `X-GAds-Quota-Project` | no | GCP project id → `x-goog-user-project`. |

> For Google Ads a service account works only with **domain-wide delegation**;
> in practice the simplest path is a ready OAuth2 access token (obtained from a
> refresh token with scope `https://www.googleapis.com/auth/adwords`) in
> `X-GAds-Access-Token`.

## Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| POST | `/googleads/customers/{customer_id}/search` | GAQL query, paginated. |
| POST | `/googleads/customers/{customer_id}/searchStream` | GAQL query, whole result set in one streamed response. |
| GET | `/googleads/customers:listAccessibleCustomers` | Customer ids the credentials can access. |

`customer_id` is the 10-digit account id (dashes are stripped for you).

### Query body (GAQL)

```json
{
  "query": "SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS"
}
```

GAQL reference:
<https://developers.google.com/google-ads/api/docs/query/overview>.

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

- **Developer token**: v Google Ads **manager (MCC) účtu → Tools → API Center**.
  Token musí mít schválený (approved) přístup, jinak vrací jen test účty.
- **customer_id**: 10místné číslo účtu (vpravo nahoře v Google Ads, bez pomlček).
- **login-customer-id**: ID manager účtu, přes který přistupujete (volitelné).
- **Access token**: vygenerujte z refresh tokenu se scope
  `https://www.googleapis.com/auth/adwords` (např. OAuth Playground) → hlavička
  `X-GAds-Access-Token`.

## Errors

Upstream errors keep the Google Ads status and body (often a detailed
`GoogleAdsFailure`) in `upstream_body`. A common one: developer token not
approved, or `login-customer-id` required for manager access.

## curl example

```bash
curl -X POST "https://services.csbot.cz/apps/analytics/googleads/customers/1234567890/searchStream" \
  -H "X-GAds-Developer-Token: <DEV_TOKEN>" \
  -H "X-GAds-Access-Token: ya29...." \
  -H "X-GAds-Login-Customer-Id: 9876543210" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date DURING LAST_7_DAYS"}'
```