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.

---

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

1. Google Ads API access

   Apply for a Developer Token and set up OAuth 2.0 credentials in the Google Cloud Console. You need at least Standard Access for production.
2. google-ads Python client

   Install with pip install google-ads. Create a google-ads.yaml config or set credentials via environment variables.
3. Mavera API key

   Get your key from Mavera dashboard.
4. Environment variables

   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	search_term_view (GAQL)	Mave Agent	Intent clusters + content plan
2	Ad Copy Performance × Persona Validation	ad_group_ad (conversions/CTR)	Focus Groups	Persona-validated copy insights
3	Keyword Research → Generate Pipeline	KeywordPlanIdeaService	Generate	SEO blog posts from keyword data
4	Demographic Performance → Persona Refinement	gender_view + age_range_view	Custom Personas	Data-backed persona library
5	Display/YouTube Placement Analysis	group_placement_view	Mave Agent	Content theme analysis
6	RSA Variation Testing	ad_group_ad (RSA assets)	Focus Groups	Headline/description scoring
7	Competitor Auction Insights → 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. 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

All Integrations

50+ API integrations with full code

Google Ads API Docs

Official Google Ads API reference

Personas API

Full reference for POST /api/v1/personas

Focus Groups API

Full reference for POST /api/v1/focus-groups

Mave Agent

Full reference for POST /api/v1/mave/chat

Generate API

Full reference for POST /api/v1/generations