A Python library that simulates the Google Ads API for development and testing purposes.
This library provides a realistic simulation of Google Ads API responses without requiring:
- Real Google Ads credentials
- Active campaigns or ad spend
- API quota consumption
- Network calls to Google services
Use Case: Develop and test marketing data pipelines, analytics systems, and campaign monitoring tools without depending on production Google Ads accounts.
- Campaign hierarchy (Account → Campaign → Ad Group → Ad)
- Realistic performance metrics (impressions, clicks, conversions, cost)
- Temporal variation (daily performance fluctuations)
- Standard Google Ads data structures
- Data engineers building marketing analytics pipelines
- Developers creating campaign monitoring tools
- Teams needing reproducible test data for CI/CD
- Students learning marketing technology stack
- Campaign names using marketing terminology
- Metrics following realistic distributions (CTR: 2-5%, CVR: 5-15%)
- Calculated fields (CPA, ROAS) derived from base metrics
- Temporal consistency (same campaign + date = same metrics)
- All metrics validated at generation time
- Impossible values rejected (negative costs, CTR > 100%)
- Relationships enforced (clicks ≤ impressions)
- Configurable number of campaigns
- Adjustable metric ranges
- Date range selection
- Seed control for reproducibility
The library exposes a single declarative entry point inspired by GAQL:
gad.config(...)
gad.create()
gad.query("SELECT ... FROM campaign WHERE ...")config() defines the laws of the simulated universe (seed, number of campaigns, Anomaly, behavior, etc).
create() freezes this universe, making it deterministic and consistent across queries.
query() does not generate data on demand -- it obeserves this pre-defined world using GAQL-like language.
Different queries issued after the same create() call always observe the same universe:
gad.query("SELECT campign.id, metrics.clicks FROM campaign")
gad.query("SELECT campign.id, metrics.conversions FROM campaign")Both queries operate over the same synthetic world, ensuring:
- "reproducibility"
- "Cross-query consistency"
- "Realistic data engineering workflow"
This mirrors how the real Google Ads API behaves: queries never create data, they reveal different projections of an existing system.
Will be installable via pip once published. For development, install from source.
Models layer - Pydantic models for Campaign, AdGroup, Metrics with validation
Generators layer - Logic for creating realistic marketing data
Client layer - Public API that consumers interact with
Configuration - Centralized settings for data generation parameters
This library prioritizes:
- Realism - Data should resemble actual Google Ads responses
- Determinism - Same inputs produce same outputs (testability)
- Validation - Invalid data cannot be generated
- Simplicity - Easy to integrate into existing projects
This is a simulation, not a wrapper. It does not:
- Connect to Google services
- Require authentication
- Respect Google Ads API structure exactly
- Support all Google Ads features
It does provide:
- Similar data structures for common use cases
- Realistic metric relationships
- Sufficient fidelity for pipeline development
- Easy migration path (swap client implementation)
The library includes comprehensive tests ensuring:
- Metrics stay within valid ranges
- Relationships between metrics are maintained
- Edge cases handled correctly (zero conversions, etc.)
- Deterministic output given same seed
Potential additions based on user needs:
- Ad group and keyword level metrics
- Geographic and demographic breakdowns
- Hourly metrics (not just daily)
- Anomaly injection for testing alert systems
This is a personal project developed for portfolio purposes. Feedback and suggestions welcome.
MIT License - free to use, modify, and distribute.
Note: This library was created as part of a data engineering portfolio project demonstrating:
- Python package development best practices
- Test-driven development
- API design
- Marketing technology domain knowledge