.png)
Google Ads Integration Guide
Integrate Google Ads with enterprise systems through its versioned REST API, GAQL reporting, mutation operations, batch processing, and scheduled synchronization.
Google Ads integration options at a glance
Google Ads provides a versioned REST API for retrieving resources, running Google Ads Query Language (GAQL) searches, generating reports, and submitting mutations. BatchJobService supports asynchronous processing for larger mutation workloads, while ChangeStatus and supported ChangeEvent resources help identify account changes. Google Ads does not provide a general webhook stream for all campaign and reporting activity, so scheduled polling and incremental queries are central to synchronization. Authentication combines OAuth 2.0, a developer token, customer IDs, and sometimes a manager-account login customer ID. Martini can orchestrate these calls, map JSON data, schedule workflows, load reporting data, and apply retry and idempotency controls.
| Integration point | Supported by Google Ads? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Retrieve customer resources, run searches and reports, read campaigns and ad groups, and submit resource mutations using versioned JSON endpoints. | Martini can consume the Google Ads REST API from workflows, centralize request configuration, transform responses, and expose normalized downstream APIs. |
| GAQL reporting and resource queries | Yes | Query Campaign, AdGroup, KeywordView, ClickView, conversion, metric, and other supported resources using Google Ads Query Language. | Martini can schedule GAQL requests, manage pagination or streaming results, validate query outputs, and load normalized data into databases or other applications. |
| Bulk and asynchronous batch APIs | Yes | Submit large collections of mutate operations through BatchJobService for campaign, budget, ad group, keyword, or other supported changes. | Martini can submit batch jobs, persist job identifiers, poll for completion, inspect operation-level failures, and route successful and failed results separately. |
| ChangeStatus and ChangeEvent | Yes | Identify changed resources and supported account changes for incremental synchronization instead of repeatedly retrieving all resources. | Martini can run scheduled incremental queries, persist cursors or timestamps, reconcile changes, and combine change tracking with periodic full or recent-period synchronization. |
| Webhooks and outbound callbacks | No | Google Ads does not provide a general webhook mechanism for all campaign, ad group, ad, keyword, and reporting changes. | Martini can implement the documented polling alternative with scheduler-triggered GAQL, ChangeStatus, and supported ChangeEvent queries; it should not assume push notifications. |
| File and asset APIs | Limited | Asset resources and upload workflows support certain asset types, such as images, but Google Ads is not a general-purpose file or attachment repository. | Martini can orchestrate supported asset API requests and transform upload metadata, while treating each asset workflow according to its resource-specific requirements. |
| Authentication | Yes | Requests generally require OAuth 2.0, a developer token, a customer ID, and a login customer ID header when accessing a client through a manager account. | Martini can keep OAuth credentials, refresh tokens, developer tokens, customer IDs, and manager-account identifiers in protected configuration or secrets. |
| SDKs and gRPC | Limited | Google publishes client libraries and a gRPC interface for several languages, but REST is the most direct fit for a Martini HTTP integration. | Martini can use REST without an SDK; custom JVM-compatible logic may be considered for specialized requirements that cannot be addressed through REST requests. |
How Google Ads exposes data and business events
Google Ads REST APIs
Google Ads provides versioned REST endpoints for customer-scoped resource retrieval, searches, reporting, and mutations. Requests use JSON and identify the customer account in the request path or resource context.
Martini implementation pattern
Martini consumes the REST endpoints from a workflow, injects protected authentication and account headers, maps responses to canonical models, and routes results to downstream APIs, databases, or applications. Mutation workflows validate inputs and inspect response details before reporting success.
Implementation sequence
Google Ads GAQL reporting
Google Ads Query Language supports resource queries and reporting across campaigns, ad groups, keyword views, click views, conversions, metrics, and date segments. Queries must use fields compatible with the selected resource.
Martini implementation pattern
Martini stores or generates controlled GAQL statements, runs them on a schedule or through an API request, handles page tokens or searchStream responses, and transforms results for warehouse or reporting use. Recent periods can be re-read to account for attribution adjustments and reporting delays.
Implementation sequence
ChangeStatus and ChangeEvent
Google Ads provides ChangeStatus and supported ChangeEvent resources for identifying changes over a limited history period. These mechanisms are alternatives to a general webhook stream, not universal push notifications.
Martini implementation pattern
Martini runs scheduled incremental workflows using a persisted timestamp or cursor, retrieves supported changes, and then fetches the current resource state where required. A periodic reconciliation query can identify missed or restated changes.
Implementation sequence
BatchJobService
BatchJobService supports asynchronous processing of multiple mutate operations. It is useful when campaign, budget, ad group, keyword, or related changes are too numerous for individual synchronous calls.
Martini implementation pattern
Martini builds and validates a bounded operation set, submits a batch job, stores the returned job identifier, and uses a follow-up workflow to poll completion. The result handler separates successful operations from partial failures and records retryable errors.
Implementation sequence
Scheduled reporting synchronization
Because Google Ads does not offer general webhooks for all account activity, scheduled synchronization is the standard pattern for reporting and broad resource reconciliation.
Martini implementation pattern
A Martini Scheduler Trigger starts a workflow for each customer and reporting window. The workflow queries recent and incremental dates, handles pagination, loads normalized results, and records a checkpoint for the next run while allowing controlled backfill.
Implementation sequence
Common Google Ads integration patterns
Pattern 1: Sync campaigns and budgets to enterprise systems
When to use this pattern
Use this pattern when finance, marketing planning, or operational applications need current Google Ads account configuration without direct coupling to Google Ads API details.
Integration direction
Example Mapping
| Google Ads Field | Canonical Field | Target Field |
|---|---|---|
| customer.id | advertisingAccountId | account_id |
| campaign.resource_name | campaignResourceName | campaign_resource_name |
| campaign.name | campaignName | campaign_name |
| campaign_budget.amount_micros | dailyBudgetMicros | daily_budget_micros |
Martini implementation pattern
A scheduled Martini workflow runs GAQL queries for Customer, Campaign, and CampaignBudget data, processes pages, maps resource names and account scope, and upserts records using stable keys. It records checkpoints, retries transient failures with backoff, and performs periodic reconciliation for missed changes.
Martini capabilities used
- workflows
- API consumption
- scheduler triggers
- data mapping
- SQL integration
- business rules
- error handling
Pattern 2: Upload offline conversions from a CRM
When to use this pattern
Use this pattern when qualified leads, opportunities, or revenue outcomes from a CRM must be attributed to Google Ads conversion actions.
Integration direction
Example Mapping
| Google Ads Field | Canonical Field | Target Field |
|---|---|---|
| ConversionAction | conversionAction | conversion_action |
| conversionDateTime | eventTimestamp | conversion_date_time |
| conversionValue | value | conversion_value |
| orderId | eventId | order_id |
Martini implementation pattern
A Martini API or workflow receives approved conversion events, validates the conversion action, timestamp, currency, value, and supported attribution identifier, then submits the Google Ads upload request. Stable event or order identifiers are stored before and after submission so retries do not duplicate conversions; rejected records are routed for review.
Martini capabilities used
- APIs
- workflows
- data mapping
- validation
- business rules
- idempotency controls
- error handling
Pattern 3: Load performance reporting into a warehouse
When to use this pattern
Use this pattern for daily campaign performance, cross-channel reporting, cost reconciliation, and historical snapshots across Google Ads accounts.
Integration direction
Example Mapping
| Google Ads Field | Canonical Field | Target Field |
|---|---|---|
| campaign.id | campaignId | campaign_id |
| segments.date | reportDate | report_date |
| metrics.clicks | clicks | click_count |
| metrics.conversions | conversions | conversion_count |
Martini implementation pattern
Martini executes version-controlled GAQL queries for Campaign, AdGroup, KeywordView, ClickView, and conversion data. It handles pagination or searchStream processing, converts metric types, upserts by account, resource, and date, and reprocesses recent dates to accommodate attribution adjustments and reporting delays.
Martini capabilities used
- scheduled workflows
- GAQL API consumption
- data mapping
- JSON processing
- database or warehouse integration
- checkpointing
- monitoring
Pattern 4: Govern campaign and keyword mutations
When to use this pattern
Use this pattern when an internal application must request campaign, budget, ad group, or keyword changes while enforcing approval, naming, spending, and retry rules.
Integration direction
Example Mapping
| Google Ads Field | Canonical Field | Target Field |
|---|---|---|
| campaign.resource_name | campaignResourceName | campaign |
| campaign_budget.amount_micros | requestedBudgetMicros | amount_micros |
| ad_group_criterion.keyword.text | keywordText | keyword.text |
| ad_group_criterion.status | criterionStatus | status |
Martini implementation pattern
A Martini API receives a change request, validates customer scope and business rules, checks existing resource names, and submits controlled mutation operations. The workflow logs request and response context, distinguishes partial failures from transport errors, retries only safe operations, and returns an auditable outcome to the calling application.
Martini capabilities used
- API exposure
- workflows
- validation
- business rules
- data transformation
- mutation orchestration
- audit logging
- error handling
Applications commonly integrated with Google Ads
Google Ads is commonly included in marketing, sales, ecommerce, measurement, and enterprise analytics architectures. Martini can coordinate data movement between Google Ads and named applications using their supported APIs, normalize data, apply business rules, and preserve operational controls across the workflow.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Import qualified leads, opportunities, and revenue outcomes as offline conversions while synchronizing campaign attribution and reporting with CRM data. | Salesforce → Martini → Google Ads | A Martini workflow receives approved conversion events from Salesforce, validates conversion actions and attribution identifiers, prevents duplicates, and submits the relevant Google Ads conversion upload request. Separate scheduled workflows can retrieve campaign metadata and reporting data for Salesforce or a shared data store. |
| HubSpot | Send lifecycle-stage changes and qualified lead events to Google Ads and combine advertising performance with marketing automation data. | HubSpot → Martini → Google Ads | Martini consumes HubSpot events or scheduled extracts, maps lifecycle data to Google Ads conversion actions, and submits validated conversions. GAQL reporting workflows can normalize campaign and conversion metrics for HubSpot or a reporting destination. |
| Shopify | Relate ecommerce orders and customer conversions to Google Ads campaigns and upload eligible purchase conversions. | Shopify → Martini → Google Ads | A Martini workflow receives order data from Shopify, identifies eligible purchases, maps order value, currency, timestamp, click identifiers, and order ID, then uploads conversions with idempotency checks. Reporting workflows can send campaign performance to a warehouse. |
| Google Analytics 4 | Reconcile advertising traffic, conversions, and campaign performance across Google measurement products. | Google Ads → Martini → Google Analytics 4 | Martini retrieves Google Ads reporting data, applies common campaign and date dimensions, and routes normalized results to an approved Google Analytics 4 integration endpoint or shared reporting model where the required APIs and permissions are available. |
| BigQuery | Centralize campaign spend, clicks, conversions, and historical reporting with CRM, ecommerce, and finance data. | Google Ads → Martini → BigQuery | Scheduled Martini workflows execute GAQL queries, partition or page results, transform resource names and metrics into warehouse tables, and backfill recent reporting dates to account for attribution adjustments and reporting delays. |
| Snowflake | Load governed Google Ads performance and attribution data into an enterprise analytics warehouse. | Google Ads → Martini → Snowflake | Martini runs account- and date-scoped GAQL queries, maps Campaign, AdGroup, KeywordView, ClickView, and conversion data to a canonical model, and writes bounded batches to Snowflake through the available database or API interface. |
| Microsoft Advertising | Combine Google Ads and Microsoft Advertising data for cross-channel reporting, spend comparison, and budget analysis. | Google Ads → Martini → Microsoft Advertising | Separate Martini workflows retrieve each advertising platform's data, transform platform-specific fields into a shared campaign and metric model, and publish the consolidated result to a reporting database or API. |
| Looker Studio | Provide consolidated marketing dashboards when Google Ads data must be transformed or combined with operational sources before presentation. | Google Ads → Martini → Looker Studio | Martini retrieves and normalizes Google Ads reporting data, joins it with approved CRM, ecommerce, or finance sources, and exposes or loads the resulting model through a reporting destination that Looker Studio can consume. |
How to build a Google Ads integration in Martini
Objective
Establish Google Ads access using the required OAuth 2.0 authorization, developer token, customer ID, and manager-account context where applicable.
Instructions in Martini
- Create protected Martini configuration for OAuth credentials and tokens
- Store developer tokens, customer IDs, and login customer IDs as secrets or environment configuration
- Configure the REST API request with the required authorization and account headers
- Separate development, test, and production credentials where possible
Objective
Select scheduled polling, an exposed Martini API, or an upstream application event according to the Google Ads use case.
Instructions in Martini
- Use a Scheduler Trigger for reporting and incremental synchronization
- Expose a Martini API for controlled campaign changes or conversion submissions
- Do not design the integration around general Google Ads webhooks
- Persist the last successful timestamp, cursor, or reporting watermark
Objective
Retrieve Google Ads resources and reports or receive validated data from a CRM, ecommerce, or internal application.
Instructions in Martini
- Build versioned REST and GAQL requests for the required customer account
- Handle page tokens, searchStream responses, or bounded result batches
- Retrieve current resources after ChangeStatus or ChangeEvent detection when required
- Validate incoming conversion and mutation payloads before processing
Objective
Coordinate API calls, pagination, batching, enrichment, checkpoints, and target-system operations in a maintainable Martini workflow.
Instructions in Martini
- Separate reporting, mutation, and conversion-upload flows where their operational characteristics differ
- Use BatchJobService for suitable high-volume mutation workloads
- Persist job identifiers, checkpoints, resource names, and request context
- Route successful, rejected, and retryable results separately
Objective
Convert Google Ads resources, GAQL rows, metrics, dates, identifiers, and status values into a canonical or target-specific model.
Instructions in Martini
- Map Customer, Campaign, AdGroup, AdGroupAd, AdGroupCriterion, and CampaignBudget fields explicitly
- Normalize customer IDs without hyphens and retain full resource names
- Convert micros, dates, currencies, and metric types according to target requirements
- Keep GAQL statements and field mappings version-controlled
Objective
Enforce account scope, approval, spend, conversion quality, deduplication, and data-governance rules before writing or mutating data.
Instructions in Martini
- Validate customer and manager-account relationships
- Check stable business keys before create operations
- Use order IDs or equivalent identifiers for conversion deduplication where supported
- Reject incompatible GAQL fields, invalid date ranges, and incomplete conversion data
Common Google Ads data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Customer | Represents a Google Ads account and its account-level configuration, users, billing settings, and owned resources. | CRM, finance platforms, data warehouses, reporting APIs | Martini scopes requests by customer ID, normalizes account metadata, and preserves manager-account versus client-account context. |
| Campaign | Contains campaign-level budget, bidding, targeting, status, and advertising configuration. | Marketing planning systems, CRM, data warehouses, reporting platforms | Martini retrieves Campaign resources through GAQL or REST, maps resource names and statuses, and validates mutations before submission. |
| AdGroup | Groups ads and related targeting criteria within a Campaign. | Marketing operations applications, reporting databases, campaign management APIs | Martini synchronizes AdGroup relationships, applies naming and status rules, and handles campaign and customer scoping. |
| AdGroupAd | Represents an ad associated with an AdGroup, including ad content and serving status. | Content review systems, marketing platforms, reporting stores | Martini maps ad content and serving state, applies approval rules, and inspects partial failures returned by mutation operations. |
| AdGroupCriterion | Represents targeting or exclusion criteria such as keywords, audiences, and placements. | Keyword management tools, campaign planning systems, data warehouses | Martini uses stable resource names and business keys, validates targeting changes, and applies safe retry and duplicate controls. |
| CampaignBudget | Defines a campaign budget and associated delivery configuration. | Finance systems, budget planning applications, campaign management APIs | Martini synchronizes budget values and status, validates thresholds, and submits controlled updates through mutation operations. |
Authentication and security considerations
Authentication requirements
Google Ads API requests generally require OAuth 2.0 authorization with the Google Ads scope, a developer token, and a customer ID. Access through a manager account may also require the login customer ID header.
Protect account credentials
- Store OAuth client details, refresh tokens, developer tokens, customer IDs, and manager-account identifiers in protected Martini configuration or secrets.
- Keep customer and manager-account scope explicit to avoid sending requests to the wrong account.
- Use separate credentials and account environments for development, testing, and production where possible.
- Apply organizational privacy, consent, and data-retention requirements to conversion and customer data.
Operational considerations for Google Ads integrations
Quotas and pagination
Developer-token access levels, request quotas, operation limits, customer restrictions, page tokens, and searchStream behavior affect workflow design. Centralize API settings, use bounded batches, and avoid repeated broad queries.
Reporting and synchronization
GAQL fields must be compatible with the selected resource and reporting context. Persist checkpoints, reprocess recent dates when appropriate, and account for attribution windows, conversion adjustments, and reporting delays.
Mutations and reliability
- Use stable resource names and business keys to make create and update behavior predictable.
- Inspect partial failures instead of treating an HTTP-success response as proof that every operation succeeded.
- Apply exponential backoff to transient failures and retry only operations that are safe to repeat.
- Pin API versions, test GAQL and mutation payloads during upgrades, and monitor version sunset notices.
- Log customer scope, request context, job identifiers, checkpoints, and final outcomes without exposing secrets.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration beyond point-to-point calls
Martini separates Google Ads API consumption from downstream application logic, allowing workflows to coordinate reporting, conversion uploads, campaign mutations, databases, and enterprise APIs in one maintainable integration layer.
Reusable transformation and control
Mappings, validation, business rules, checkpoints, idempotency controls, batching, and error handling can be reused across customers and integration flows instead of being duplicated in scripts.
Operational visibility
Scheduled workflows, protected configuration, structured logging, retry handling, and controlled API exposure provide a clearer operational model than isolated scripts or tightly coupled point-to-point integrations.
Frequently asked questions
Google Ads can be integrated through its versioned REST API, GAQL resource and reporting queries, mutation operations, BatchJobService, and supported ChangeStatus or ChangeEvent resources. Enterprise workflows commonly use scheduled synchronization because Google Ads does not provide a general webhook stream for all account activity.
Yes. Martini can consume the Google Ads REST API, run GAQL queries, submit mutation and offline conversion requests, orchestrate batch jobs, transform JSON data, schedule synchronization, and load results into downstream applications or databases.
No. A dedicated Google Ads connector is not required. Martini can integrate using Google Ads native REST endpoints, OAuth 2.0, developer-token authentication, customer-account headers, GAQL, batch operations, and supported change-tracking resources.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Google Ads. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Google, cloud infrastructure, or other third-party systems based on subscriptions, API usage, and deployment model.
New integrations should use the versioned Google Ads REST API with GAQL for resource retrieval and reporting, mutation operations for controlled changes, and BatchJobService for suitable asynchronous workloads. The former SOAP-based AdWords API is legacy and has been sunset; no official Google Ads GraphQL API was identified.
Google Ads does not provide a general webhook mechanism covering all campaign, ad group, ad, keyword, and reporting changes. Martini should use scheduled GAQL queries, ChangeStatus, and supported ChangeEvent resources for incremental synchronization.
Synchronization is typically scheduled and customer-scoped. Martini can query GAQL reports by date, preserve page tokens or timestamps, use ChangeStatus or ChangeEvent for supported changes, upsert by stable resource names, and reprocess recent dates to account for reporting delays and attribution adjustments.
Martini can validate requests, apply exponential backoff for transient failures, inspect partial-failure responses, and route rejected operations for review. Stable resource names, request identifiers, order IDs, checkpoints, and pre-create existence checks help prevent duplicate mutations and conversion uploads.
Related Martini documentation
Workflows
API Integration
Data and Security
Integrate Google Ads with Martini
Use Martini to build governed Google Ads integrations for reporting, conversion uploads, campaign operations, and enterprise data synchronization.