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)

{
  "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

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"}'

3.1 KiB Raw Blame History