Google Ads API Interface • r4googleads

Welcome to the official documentation of the R {r4googleads} software package! {r4googleads} enables users of the R Project for Statistical Computing to smoothly access their Google Ads account to load and analyze information provided by the Google Ads API.

The Ads API is Google’s latest application programming interface (API) to its Ads platform and the next generation of the AdWords API. The Ads API enables Google Ads customers to interact with Google’s advertising platform using a programming language. {r4googleads} helps you to implement your advertising performance analytics in R and increase your efficiency, make your reports reproducible and flexible enough to managing even large, complex Google Ads accounts and campaigns.

Developed by the Creators of RAdwords

{r4googleads} is the leading R client library for the Google Ads API developed by Matthias Bannert and Johannes Burkhardt. Since 2014, the duo has developed and maintained RAdwords, the #1 R client library for Google’s predecessor Adwords API. That’s 66K+ downloads and, more importantly, 7 years of experience and reliable maintenance of an open source package.

Let’s move on to the all new {r4googleads} ! (check our migration guide!)

Why {r4googleads} ?

Connect your Google Ads reports to the R Language for Statistical Computing. Unlock the next level of campaign and marketing performance analytics -> Learn how to analyze Google Ads statistics and Key Performance Indicators (KPIs) using a license cost freeeee open source programming language. Automate your reports on accounts, campaigns, adgroups and keywords data reliably.

authenticate with the Google Ads API
light dependencies on other R packages for stable long term production
List top-level Google Ads accounts
query Google Ads API reports with the Google Ads Query Language
Load statistics, metrics and KPIs from Google Ads API including account, campaign, adgroup and keyword data
Load data schema of Google Ads API reports including resource metadata, resource fields, segments and metrics

What Does {r4googleads} Not Do?

the package does not sign you up @Google (you need an existing acocunt)
the package does not implement statistical methods. (the R language is second to none when it comes the amount of methodological extension packages. Pick your methods for statistical analysis from more than 18K extension packages. )

Quick Start Guide

Requirements

This guide assumes you have set up a working Google Ads API Developer Token and a Google Cloud Project. If you are starting from scratch or have trouble wrapping your head around Google’s complex portfolio, stay tuned for our ultimate guide dropping in Spring 2022 !

R Package Installation Notes

Install the latest stable version of {r4googleads} from R’s official Comprehensive R Archive Network (CRAN) or

install.packages("r4googleads")

install the latest development release from GitHub using the {remotes} R package. (the below example code assumes the {remotes} package is installed.)

remotes::install_github("banboo-data/r4googleads")

Authentication

Ok, once {r4googleads} is installed, the stage is set (Google accounts are set up and dev tokens are available, too) and the air is clear, start to authenticate at Google’s servers.

library(r4googleads)
google_auth <- authenticate()

This will start an interactive 1-2-3 process:

Spin up your default web browser and display Google’s login form
login using your credentials
receive a token that’s kept in your session (google_auth variable) and stored in an .RData file

congrats, you are ready to load data into your R session!

Load Data

To specify which data data you want to load into your R session you can use Google’s own SQL reminiscant query language. Visit the link to find out about available reports and validate your queries online.

g_query <- "SELECT
                campaign.name, 
                campaign.status,
                segments.device, 
                metrics.impressions,
                metrics.clicks, 
                metrics.ctr,
                metrics.average_cpc, 
                metrics.cost_micros
              FROM campaign
              WHERE segments.date DURING LAST_30_DAYS
              AND metrics.impressions > 0
              PARAMETERS include_drafts=true"

The next step is to create a service object that contains the query string, your Google Ads Account ID and the API version you want to use. The example uses one of our 3 constructors to create different service objects: googleAdsSearch, googleAdsFields, listAccessibleCustomers.

query_service <- googleAdsSearch(
  aid = '***-****-***', # Google Ads Account ID
  query = g_query,
  api_version = 'v9'
  )

the resulting service query object can be passed on to the query_google_ads functions which sends the service object to Google’s actual API service. Note, that a MCC ID is needed here. The handler inside query_google_ads processes the service object depending on its class and starts the corresponding request.

d <- query_google_ads(
  mcc_id = '***-***-****', # Google Ads My Client Center ID
  google_auth = google_auth,
  service = query_service,
  raw_data = F
)

The object d is a data.frame that contains the Google Ads statistics:

campaign.resourceName	campaign.status	campaign.name	metrics.clicks	metrics.costMicros	metrics.ctr	metrics.averageCpc	metrics.impressions	device
customers/*********/campaigns/354500548	ENABLED	Brands	139	35770000	0.0630672	257338.13	2204	DESKTOP
customers/*********/campaigns/14704583758	ENABLED	google_shopping_de	33	2190000	0.0141086	66363.64	2339	DESKTOP
customers/*********/campaigns/354500548	ENABLED	Brands	628	159470000	0.0828168	253933.12	7583	MOBILE
customers/*********/campaigns/14704583758	ENABLED	google_shopping_de	64	6370000	0.0105471	99531.25	6068	MOBILE
customers/*********/campaigns/354500548	ENABLED	Brands	20	5240000	0.0473934	262000.00	422	TABLET
customers/*********/campaigns/14704583758	ENABLED	google_shopping_de	0	0	0.0000000	NA	234	TABLET

Load Google Ads Data Into Your R Session