Skip to main content
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

DetailValue
Base URLhttps://googleads.googleapis.com/v23/ (REST) or gRPC
AuthOAuth 2.0 access token + Developer Token header
Rate limitsDynamic QPS (automatically adjusted); unlimited daily operations with Standard Access
Python clientgoogle-ads SDK — wraps gRPC with GAQL support
Mavera basehttps://app.mavera.io/api/v1
Mavera authAuthorization: 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

#JobGoogle Ads DataMavera SurfaceOutput
1Search Term → Content Strategysearch_term_view (GAQL)Mave AgentIntent clusters + content plan
2Ad Copy Performance × Persona Validationad_group_ad (conversions/CTR)Focus GroupsPersona-validated copy insights
3Keyword Research → Generate PipelineKeywordPlanIdeaServiceGenerateSEO blog posts from keyword data
4Demographic Performance → Persona Refinementgender_view + age_range_viewCustom PersonasData-backed persona library
5Display/YouTube Placement Analysisgroup_placement_viewMave AgentContent theme analysis
6RSA Variation Testingad_group_ad (RSA assets)Focus GroupsHeadline/description scoring
7Competitor Auction Insights → Battle Cardsauction_insightsMave AgentCompetitive battle cards

​
Rate Limits & Production Notes

Google Ads EndpointLimitStrategy
GAQL Search/SearchStreamDynamic QPS (auto-throttled)Retry on RESOURCE_EXHAUSTED with exponential backoff
KeywordPlanIdeaServiceLower QPS than reportingCache results; batch seed keywords
Mutate operations10,000 operations/requestN/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:
ConcernRecommendation
Token refreshUse google-ads client library’s built-in refresh flow. For REST, exchange refresh tokens via https://oauth2.googleapis.com/token.
Customer IDsUse Login Customer ID header (login-customer-id) for MCC accounts managing multiple child accounts.
GAQL date rangesAlways include segments.date DURING to avoid pulling lifetime data. LAST_30_DAYS is a safe default.
Paginationsearch returns pages; searchStream returns all rows in one response. Prefer searchStream for batch jobs.
Mavera creditsMonitor usage at Dashboard. Each Mave chat call consumes credits proportional to prompt length.
SecretsStore 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