YourPPCLab Ads Reporting — Tool Design Document
Download PDF1. Company and purpose
YourPPCLab is an independent performance-marketing practice (owner: Alexander, 15 years in search and social advertising). We manage paid search for a small number of advertisers, mainly YouTravel.me (tour marketplace) and Sokratic (AI presentation generator, sokratic.ru).
The tool is a set of internal Python scripts running on our own server. They read performance data from the Google Ads accounts we manage, build daily reports for us and our clients, and apply campaign changes that a specialist has prepared and reviewed. The tool is used internally only. We do not offer it to third parties and do not sell API access or data.
2. Users and accounts
| Item | Details |
|---|---|
| Users | 1–2 PPC specialists of YourPPCLab. Clients only see read-only HTML reports. They never get direct access to the API or the tool. |
| Accounts | Only accounts where we were given access by the advertiser. MCC 878-998-3937 (YouTravel.me) → client account 227-948-0150; Sokratic account 956-463-9462 (direct access). |
| Authentication | OAuth 2.0 (installed-app flow), one Google user who is an admin on these accounts. The refresh token and developer token are stored on our server and readable only by the service user (file permission 600). |
| API version | Google Ads API v22, REST interface. |
3. Architecture
cron (daily) → Python scripts → Google Ads API (GoogleAdsService.Search) → JSON files on server → HTML report generator → private reports on our web server- Data collection: scheduled once per day at 09:45 Moscow time. Incremental where possible, e.g. change history is accumulated locally because
change_eventonly covers 30 days. - Reporting: static HTML pages with charts: daily conversions, cost and CPA, device split, search terms, change log. Data is joined with the client's own CRM and analytics data.
- Campaign management: a specialist prepares changes (new campaigns, keywords, negative keywords, budgets, target CPA). These go through a dry run, then are applied with
mutatecalls. Nothing is changed automatically without human review. - Keyword planning (requested with this application): keyword ideas and historical search volume for campaigns we are building in accounts we manage. Example: a separate Sokratic campaign for competitor brand queries in Kazakhstan and Belarus.
4. API services used
| Service / method | Resources | Purpose |
|---|---|---|
| GoogleAdsService.Search | customer, campaign, ad_group, ad_group_ad, keyword_view, search_term_view, click_view, geographic_view, user_location_view, age_range_view, gender_view, campaign_criterion, shared_set, conversion_action, change_event, recommendation | Reporting, audits, change history, device analysis by GCLID |
| GoogleAdsService.Mutate | Campaign, CampaignBudget, AdGroup, AdGroupAd, AdGroupCriterion, CampaignCriterion, SharedSet / SharedCriterion | Applying reviewed changes: campaign creation, keywords and negatives, budgets, bidding targets |
| KeywordPlanIdeaService (new) | GenerateKeywordIdeas, GenerateKeywordHistoricalMetrics | Search volume and ideas for keywords in campaigns we manage (competitor and category keywords; geo KZ / BY / RU; language Russian) |
Expected volume
Current usage is about 200–500 operations per day for reporting. Occasional bulk campaign builds need up to 3,000–8,000 operations per day, which exceeds the Explorer limit of 2,880. Keyword planning will add about 50–200 requests per week. Basic access (15,000 operations per day) covers all of this.
5. Feature details
5.1 Daily performance report
Conversions (purchases), cost and CPA by day, campaign and market. It also shows a change log built from change_event (who changed what), plotted as event markers on the charts.
5.2 Account audit
A read-only audit covering structure, budget and rank-lost impression share, search terms with and without conversions, competitor queries, ad strength and segments. The output is a list of recommendations for the specialist.
5.3 Campaign management
Bulk creation and editing of search campaigns prepared by the specialist: keywords, negative keyword lists, budgets and target CPA. Every run is logged, and changes are visible in the Google Ads change history.
5.4 Keyword planning (requested)
For a planned competitor campaign we need search volume, competition and bid ranges for about 300–500 brand and category keywords. We fill the seed lists from our own search-term data, call GenerateKeywordHistoricalMetrics / GenerateKeywordIdeas, and save the results to an internal spreadsheet. The specialist then uses it to choose keywords, match types and budgets. The data is not resold or published as a standalone keyword research product.
6. Compliance and data handling
- Internal tool, used only for accounts we are authorized to manage. No external users and no white-label access.
- Credentials are stored on a single server with restricted permissions and are never sent to third parties.
- API data is used only to report on and optimize the advertiser's own campaigns, and is shared only with that advertiser.
- We follow the Google Ads API Terms and Conditions and the Required Minimum Functionality policy, where applicable. We respect rate limits and use exponential backoff on errors.
7. Contact
YourPPCLab — yourppclab.ru. Contact email: yurkov.alexander@gmail.com.