Google Ads API Tool — Design Document

1. Overview & Purpose

This is an internal-only tool, built and operated by MECE, used exclusively to manage MECE's own Google Ads accounts (owned and linked under our own manager account). It is not offered to any third party, is not resold, and is not embedded in any product distributed to clients or the public.

Its purpose is twofold:

• Reporting: automated retrieval of campaign performance metrics (impressions, clicks, cost, conversions, CTR, CPC, ROAS) to produce internal dashboards and periodic summaries for management.
• Management & optimization: reviewing and adjusting campaign budgets, keywords, bids and status on our own accounts, based on the performance data above.

2. Who Uses the Tool

3. System Architecture

• Runtime: a Python service running on MECE's own private server. No browser, no client-side code, no public endpoint exposing the API.
• Authentication: OAuth 2.0 with offline refresh token, generated by the MECE account owner. Credentials (client secret, refresh token, developer token) are stored in a restricted, file-permission-protected secrets directory (chmod 600) and never hard-coded or transmitted to third parties.
• Library: official google-ads Python client library (v31).

4. Capabilities Provided

The tool provides the following capabilities, strictly on MECE's own accounts:

• Account Management — review settings and status of our own linked accounts.
• Campaign Creation — programmatically create new campaigns (Search, Performance Max, Display) for MECE.
• Campaign Management — adjust budgets, bids, status and structure of existing campaigns.
• Reporting — retrieve performance metrics for internal dashboards and summaries.
• Keyword Planning Services — keyword research, search-volume and forecast data to inform optimization.

Not provided: Account Creation (we do not create new Ads accounts), and no third-party/external functionality.

5. Google Ads API Services Used

6. Typical Reporting Query (GAQL example)

SELECT campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS

7. Compliance & Operational Practices

• Rate limits: requests are batched and retried with exponential backoff; the tool respects API quotas and avoids redundant polling (scheduled, not high-frequency).
• Data storage: retrieved data is stored only on MECE's own private infrastructure for internal reporting; it is not shared with or sold to any third party.
• Required Minimum Functionality (RMF): the tool supports campaign management, reporting, and budget/keyword operations on MECE's own accounts, exceeding RMF requirements.
• Policy compliance: the tool complies with the Google Ads API Terms of Service and the Required Minimum Functionality policy. The API contact email is kept current.

8. Mockup — Internal Reporting Dashboard