R has many uses, a particular highlight being its simple integration with various APIs, such as the Google Analytics API. These simple API integrations usually rely on packages, and integration into the Google Adwords API is no different. We have built our own R package for interacting with the Adwords API: adwordsR.
How does the adwordsR package work?
The current version of the adwordsR package (0.3.1) has three basic components: Google authentication via OAUTH2, reporting, and SOAP requests.
- Google Authentication
This has effectively two parts: generating the access token and refreshing the access token. All the user has to do is try and load their token. This will either generate the access token if it does not exist in their work directory, or load the existing acess token.
Users must have their client ID, client secret, and Adwords Developer token handy and enter them when prompted.
- Reporting
This accesses the reporting service from the Adwords API. It works by building the AWQL query, and then sending it to the API. The response is then a CSV text file which is cleaned into the requested format.
- SOAP Requests
This is for accessing all parts of the API that are not reporting. The package allows you to choose the service that you want to access and then builds an XML file for you. The XML file is sent to the API and an XML response is returned.
Unfortunately, the XML response is not cleaned on its response, however we do highly recommend the XML package as this can parse an XML file into a list. We do plan to integrate XML parsing functionality into future versions.
A diagram of the workflow of retrieving Adwords data using adwordsR is found below.
Why did we build the adwordsR package
Before the adwordsR package, we had raw R code in our processes and applications that didn’t make the code particularly elegant, or we needed to copy the functions from elsewhere when we wanted to reuse it.
Yes, we could have stored the functions in a file, and called those source files, but this is basically how a package works – so why not build it properly?
The advantage of building the functions into a package is that we now have clean code that is much easier to maintain, which saves us a world of time when we want to upgrade any of our toolkit.
Will it make my life easier?
If you use R and Adwords, this package will make it much easier to get data from the API through a robust process, rather than just exporting files and data from the Adwords interface.
If you’ve already used the RAdwords package, the main points of interest are for parts of the Adwords API that are not easily accessible using R. You can easily get a list of all of your clients that are child to your parent’s MCC account using the ManagedCustomerService, or search volumes using the TargetingIdeaService, like we see below.
Why did we not want to rely on the RAdwords package?
The current RAdwords package is great – we’ve learnt a great deal from this package and incorporated a lot of its concepts into our package. But unfortunately, RAdwords was lacking for our requirements and did not offer us is the ability to interact with other sections of the Adwords API, such as the Managed Customer Service, which was a necessity.
Our package aims to integrate multiple services within the Adwords API into one package. Currently, the package is limited to Reporting, the Managed Customer Service, and the Targeting Idea Service. However, we plan to integrate more services into the package.
Why did we not build on the RAdwords package instead of building an entirely new package?
Before building the package, we had our R code hardcoded into our processes. The sections of the code that did not rely on the RAdwords package were hardcoded and the functions that were built were declared within the session.
They did not come from the RAdwords package, and for ease of use we decided to build these into a package. We then decided to incorporate the workflow of the RAdwords package into our own package so that two packages did not have to be loaded within the process.
By using this approach, it was an opportunity to revamp our existing adwordsR code and the RAdwords code. As such, we do recognise the author of the RAdwords package, Johannes Burkhardt, to be a large contributor of the adwordsR package, as this package would not exist without the existence of the RAdwords package.
Where can I access and install the package?
There are multiple places that you can get the package, and all it takes is a line of R code, depending on your preferred method.
I present two methods here of acquiring the package: CRAN and CRAN Github. All you need to do is copy and paste either of the following pieces of code and run them on your installed R version
- CRAN:
install.packages("adwordsR")
- Github:
devtools::install_github("cran/adwordsR")
Alternatively, contact us for a tarball of the package.
Let us know how you’ve been using the adwordsR package!
