Migrating from AdWords API to Google Ads API. A Comprehensive Guideline

Why and how do you migrate to the latest API version using the R programming language? From RAdwords to rgoogleads package. 

Earlier I wrote a lot about using the R programming language and the RAdwords package to access data from the advertising accounts of one of the world's most popular advertising platforms, Google Ads (ex-Google AdWords). 

The problem is that the RAdwords package is used to work with Google AdWords API v201809. This API has not been updated for a long time and will stop working on 27 April 2022. 

In this article, I want to share some information on a new package, rgoogleads, which I started working on in June 2021. The package currently has all the functions needed to request the function data. Next, we will go through the details of how to switch from RAdwords to rgoogleads, so that from April 2022, your scripts will still correctly collect the necessary data from your Google Ads accounts.

This article will be of use to those with some R code writing skills and who have worked with the RAdwords package. But even if this is the first time you have heard of this language and RAdwords, there are code examples in the article. You need to enter the IDs of your Google Ads accounts and request the necessary data.

Rgoogleads package features

The rgoogleads package currently includes all the functions needed to fetch data from the Google Ads API:

• authorize in Google Ads API;
• import the list of top-level accounts;
• import the entire account hierarchy from management accounts;
• import the ad account objects: campaigns, ad groups, ads, and more;
• import statistical data from advertising accounts;
• import resource metadata, resource fields, segments, and metrics;
• import forecast and historical data from the keyword planner.

Rgoogleads package benefits

Now let's look at the benefits of switching to the new rgoogleads package:

• rgoogleads is used to work with Google Ads API v8 (released on 09.06.2021); RAdwords is used to work with Google AdWords API v201809. Google AdWords API will sunset on 27.04.2022;
• rgoogleads uses the gargle package for authorization, which gives much more flexibility than the RAdwords authorization process;
• rgoogleads has an embedded Google Ads developer token and an OAuth client for authorization. This will save most users from having to request basic access to the Google Ads API from Google support and wasting time creating a project and OAuth client in the Google Cloud Console;
• most rgoogleads functions have a cl argument, which allows for multi-threaded data import;
• unlike RAdwords, rgoogleads has a list and account hierarchy import function;
• rgoogleads has separate functions to import the main objects of the advertising accounts, such as advertising campaigns, ad groups, keywords, and ads;
• since data request is not divided into separate functions, the syntax of rgoogleads is more straightforward and concise. In RAdwords, you had to initially create statement() function and then use it to request the data in the getData() function;
• rgoogleads has no problem importing names containing Cyrillic characters;
• if the API request encounters a server failure (response status 429 or higher), the rgoogleads package will automatically pause for 100 seconds and try to request data again. This makes this package more stable and resilient to Google Ads API server failures;
• rgoogleads displays a detailed error message. In comparison, RAdwords will not display a message if the user has made a request error;
• rgoogleads allows you to request data from the Keyword Planner.

Key differences between the Google AdWords API and Google Ads API

Fortunately, there are few key differences between the old and new APIs, and the migration process isn’t that difficult. Let me enumerate the key points of the migration below.

• no need to change auto-ionization data; the developer token, ID, and client secret OAuth can also be used for a new Google Ads API;
• The AdWords API reporting is a separate service, while Google Ads API reporting is part of the same service. All you need to do is include the necessary metrics fields in your reports;
• In AdWords API, there were report types such as CAMPAINGN_PERFORMANCE_REPORT. The Google Ads API doesn't have them; instead of report types, it consists of a vast number of resources;
• AdWords API and Google Ads API have different API response formats;
• there is no includeZeroImpressions parameter in Google Ads API; instead, you can use the metrics.impressions > 0 filter.

Rgoogleads installation

The package is already available for download from CRAN, but as it is currently under active development, I recommend installing the most up-to-date version from GitHub.

# install from github
devtools::install_github('selesnow/rgoogleads')

Within a few months, the package functionality will be finalized, after which I recommend installing it specifically from CRAN.

# install from CRAN
install.packages('rgoogleads')

How rgoogleads authorisation works

Almost any API requires authorization. The gargle’s functionality is used here; therefore, the authorization process will be familiar to users of such packages as googlesheets4, googledrive, bigrquery, googleAnalyticsR.

The easiest way to log in is to use the gads_auth() function, passing the username you want. This is probably the way most package users will choose:

gads_auth(email = 'me@gmail.com')

After running gads_auth(), you will be redirected to the browser, where you need to grant the package all the necessary permissions. 

If everything was done correctly, you’ll see the notification «Authentication complete. Please close this page and return to R».

More advanced users can configure authorization. That is, if you have your Google Ads developer token and/or OAuth client, you can authorize using your registration details. Authorisation configurations can be set up using the gads_auth_configure() function.

Basic arguments of gads_auth_configure():

• path — a path to JSON file with OAuth client data;
• app — OAuth client data created via httr::oauth_app();
• developer_token — your developer token

It is essential to consider when setting up the configuration:

1. A company, i.e., a legal entity, can only have one developer token;
2. The first time you use an OAuth client from a Google Cloud project with a developer token, the client ID is linked to the developer token and cannot be used with another developer token. Put simply:
• the developer token can be used with multiple client IDs;
• the OAuth client ID can only be used with one developer token.

If you use your own developer token, you must use the OAuth client you have created. If using the built-in developer token, you can use either the built-in or your own OAuth client.

To learn how to create and configure an OAuth client (an app in Google Cloud), read «How to import data from Google Analytics API to R: Pt. 2».

You can request your developer token from the manager account only: Tools & Settings — API Centre.

If you need to authenticate using your developer token and/or your OAuth client, use the following code example:

# authorization configuration
gads_auth_configure(
    path = 'C:/auth/app.json', 
    developer_token = "own developer token"
)

# authorization
gads_auth(email = 'me@gmail.com')

Rgoogleads package options

To make it more user-friendly and avoid setting the same arguments in every function of the package, option setting functions have been added to rgoogleads. These options are valid for the current R session.

• gads_set_customer_id() — set the client account ID for the account that you will use to request data during the session. It is also possible to set up multiple accounts at once with c("111-111-1111", "222-222-2222").
• gads_set_login_customer_id() — set the manager account ID. Use the option only if you are using advertising accounts subordinate to the manager account.

# manager account ID 
gads_set_login_customer_id("xxx-xxx-xxxxx")

# set client account 
gads_set_customer_id("yyy-yyy-yyyy")

Export Google Ads reports using rgoogleads

You can now request reports on ad campaigns, ad groups, or any other resources:

group_report <- gads_get_report(
  resource    = "ad_group",
  fields = c("ad_group.campaign",
             "ad_group.id",
             "ad_group.name",
             "ad_group.status",
             "metrics.clicks",
             "metrics.cost_micros"),
  date_from   = "2021-06-10",
  date_to     = "2021-06-17",
  where       = "ad_group.status = 'ENABLED'",
  order_by    = c("metrics.clicks DESC", "metrics.cost_micros"),
  limit       = 30000
)

The Google Ads API consists of a considerable number of resources for which you can request information using the gads_get_report() function.

Find the list and description of all available resources in the official Google Ads API documentation or by using gads_get_metadata() function.

resources <- gads_get_metadata("RESOURCE")

Each resource has its own set of available fields. You can either find the set of fields in the documentation or by requesting them with gads_get_fields().

ad_group_fields <- gads_get_fields("ad_group")

Migrating from RAdwords to rgoogleads

See the table of function correspondence in RAdwords and rgoogleads packages below.

The former report types in Google AdWords have become resources in Google Ads. See the comparison table from the official help guide:

See the official help guide for the correspondence between the "Report" and the resource fields. The table is large, so there’s no need to duplicate it here.

See the example of requesting a campaign performance report with the same set of fields, using the RAdwords package and rgoogleads below.

The request of ad campaign performance report using RAdwords

library(RAdwords)

# authorization
adwords_auth <- doAuth()

# create a request
query <- statement(
  select = c('CampaignName', 
             'Date', 
             'Clicks'),
  report = 'CAMPAIGN_PERFORMANCE_REPORT', 
  start  = '2021-06-01', 
  end    = '2021-06-30'
)

# data import
data1 <- getData(
  clientCustomerId = 'xxx-xxx-xxxx',
  statement        = query,  
  google_auth      = adwords_auth
)

The request of ad campaign performance report using rgoogleads

library(rgoogleads)

# authorization
gads_auth_configure(path = 'D:/ga_auth/app.json')
gads_auth(email = 'me@gmail.com')

# data import
data2 <- gads_get_report(
  resource = 'campaign', 
  fields   = c('campaign.name', 
               'segments.date', 
               'metrics.clicks'), 
  date_from         = '2021-06-01', 
  date_to           = '2021-06-30',
  customer_id       = '676-642-7440', 
  login_customer_id = 'xxx-xxx-xxxx'
)

Useful links

Please see the following resources to deepen your understanding of rgoogleads:

1. Official documentation
2. Package on CRAN

Conclusion

If you are using RAdwords to import data from your advertising accounts, you should start converting your scripts to the rgoogleads package now. Otherwise, data collection from your accounts is likely to stop working from 27 April 2022.

The material in the article can even be used by those who haven't worked with requesting data from Google AdWords API or Google Ads API before. All you need to do is install the R language and RStudio development environment, copy the code examples from the article, and enter your account IDs. If you need help installing the required software, watch this video tutorial. You can also start mastering R programming with the free "R Language for Excel Users" course.

If you are interested in or planning to learn R, you will probably find my Telegram and YouTube R4marketing channel useful.

Feel free to leve your comments below. I’ll be happy to answer your questions.