> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Google Ads
> 7 production-ready jobs — search term content strategy, ad copy persona validation, keyword-to-generate pipelines, demographic persona refinement, placement analysis, RSA testing, and auction battle cards
Google Ads holds your paid search and display intelligence — search terms, ad performance, keyword opportunities, demographics, placements, RSA assets, and auction insights. These seven jobs pull that data through Mavera's surfaces (Mave Agent, Focus Groups, Personas, Generate) so your content strategy, ad copy, and competitive positioning are grounded in real campaign data.
```mermaid theme={"dark"}
flowchart TD
subgraph data["Google Ads Data"]
searchTerms["Search Terms"]
adCopy["Ad Copy"]
keywords["Keywords"]
demographics["Demographics"]
placements["Placements"]
rsaAssets["RSA Assets"]
auctionInsights["Auction Insights"]
end
subgraph surfaces["Mavera Surfaces"]
mave["Mave Agent"]
focusGroups["Focus Groups"]
personas["Personas"]
generate["Generate"]
end
subgraph outputs["Outputs"]
contentCalendar["Content Calendar"]
personaValidation["Persona Validation"]
seoContent["SEO Content"]
calibratedPersonas["Calibrated Personas"]
targetingStrategy["Targeting Strategy"]
assetTesting["Asset Testing"]
battleCards["Battle Cards"]
end
searchTerms --> mave
adCopy --> focusGroups
keywords --> generate
demographics --> personas
placements --> mave
rsaAssets --> focusGroups
auctionInsights --> mave
mave --> contentCalendar
mave --> targetingStrategy
mave --> battleCards
focusGroups --> personaValidation
focusGroups --> assetTesting
generate --> seoContent
personas --> calibratedPersonas
```
***
## API Reference Card
| Detail | Value |
| ----------------- | ------------------------------------------------------------------------------------- |
| **Base URL** | `https://googleads.googleapis.com/v23/` (REST) or gRPC |
| **Auth** | OAuth 2.0 access token + Developer Token header |
| **Rate limits** | Dynamic QPS (automatically adjusted); unlimited daily operations with Standard Access |
| **Python client** | `google-ads` SDK — wraps gRPC with GAQL support |
| **Mavera base** | `https://app.mavera.io/api/v1` |
| **Mavera auth** | `Authorization: Bearer mvra_live_...` |
All examples use four environment variables: `GOOGLE_ADS_DEVELOPER_TOKEN`, `GOOGLE_ADS_CLIENT_ID` (OAuth client), `GOOGLE_ADS_CUSTOMER_ID` (10-digit, no dashes), and `MAVERA_API_KEY`. Python examples use the `google-ads` client library; JavaScript examples use the REST API directly.
***
## Prerequisites
Apply for a [Developer Token](https://developers.google.com/google-ads/api/docs/get-started/dev-token) and set up OAuth 2.0 credentials in the Google Cloud Console. You need at least Standard Access for production.
Install with `pip install google-ads`. Create a `google-ads.yaml` config or set credentials via environment variables.
Get your key from [Mavera dashboard](https://app.mavera.io/settings/api-keys).
```bash theme={"dark"}
export GOOGLE_ADS_DEVELOPER_TOKEN="ABcdEf..."
export GOOGLE_ADS_CLIENT_ID="123456789.apps.googleusercontent.com"
export GOOGLE_ADS_CLIENT_SECRET="GOCSPX-..."
export GOOGLE_ADS_REFRESH_TOKEN="1//0d..."
export GOOGLE_ADS_CUSTOMER_ID="1234567890"
export MAVERA_API_KEY="mvra_live_xxxxx"
```
***
## Jobs
| # | Job | Google Ads Data | Mavera Surface | Output |
| - | ------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------- | -------------------------------- |
| 1 | [Search Term → Content Strategy](/integrations/google-ads/search-term-content-strategy) | search\_term\_view (GAQL) | Mave Agent | Intent clusters + content plan |
| 2 | [Ad Copy Performance × Persona Validation](/integrations/google-ads/ad-copy-persona-validation) | ad\_group\_ad (conversions/CTR) | Focus Groups | Persona-validated copy insights |
| 3 | [Keyword Research → Generate Pipeline](/integrations/google-ads/keyword-generate-pipeline) | KeywordPlanIdeaService | Generate | SEO blog posts from keyword data |
| 4 | [Demographic Performance → Persona Refinement](/integrations/google-ads/demographic-persona-refinement) | gender\_view + age\_range\_view | Custom Personas | Data-backed persona library |
| 5 | [Display/YouTube Placement Analysis](/integrations/google-ads/placement-analysis) | group\_placement\_view | Mave Agent | Content theme analysis |
| 6 | [RSA Variation Testing](/integrations/google-ads/rsa-variation-testing) | ad\_group\_ad (RSA assets) | Focus Groups | Headline/description scoring |
| 7 | [Competitor Auction Insights → Battle Cards](/integrations/google-ads/auction-battle-cards) | auction\_insights | Mave Agent | Competitive battle cards |
***
## Rate Limits & Production Notes
| Google Ads Endpoint | Limit | Strategy |
| ------------------------ | ---------------------------- | ------------------------------------------------------ |
| GAQL Search/SearchStream | Dynamic QPS (auto-throttled) | Retry on `RESOURCE_EXHAUSTED` with exponential backoff |
| KeywordPlanIdeaService | Lower QPS than reporting | Cache results; batch seed keywords |
| Mutate operations | 10,000 operations/request | N/A for read-only jobs |
Google Ads API uses **dynamic rate limiting** — QPS adjusts based on your account's access level and current load. All code should handle `RESOURCE_EXHAUSTED` (gRPC) or `429` (REST) with exponential backoff. Standard Access accounts have no daily operation limit, but burst capacity varies.
**Production checklist:**
| Concern | Recommendation |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Token refresh | Use `google-ads` client library's built-in refresh flow. For REST, exchange refresh tokens via `https://oauth2.googleapis.com/token`. |
| Customer IDs | Use Login Customer ID header (`login-customer-id`) for MCC accounts managing multiple child accounts. |
| GAQL date ranges | Always include `segments.date DURING` to avoid pulling lifetime data. `LAST_30_DAYS` is a safe default. |
| Pagination | `search` returns pages; `searchStream` returns all rows in one response. Prefer `searchStream` for batch jobs. |
| Mavera credits | Monitor usage at [Dashboard](https://app.mavera.io/settings/usage). Each Mave chat call consumes credits proportional to prompt length. |
| Secrets | Store `GOOGLE_ADS_DEVELOPER_TOKEN`, OAuth credentials, and `MAVERA_API_KEY` in a secrets manager. Never commit `google-ads.yaml`. |
***
## What's Next
50+ API integrations with full code
Official Google Ads API reference
Full reference for POST /api/v1/personas
Full reference for POST /api/v1/focus-groups
Full reference for POST /api/v1/mave/chat
Full reference for POST /api/v1/generations