Skip to contents

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


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 the latest development release from GitHub using the {remotes} R package. (the below example code assumes the {remotes} package is installed.)



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.

google_auth <- authenticate()

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

  1. Spin up your default web browser and display Google’s login form
  2. login using your credentials
  3. 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
              FROM campaign
              WHERE 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 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