Use External Data In Your AdWords Campaigns With Scripts To Call APIs

The 2016 Presidential primary race is in full swing here in the United States. You really can’t go anywhere without hearing the latest polling results. While these polls certainly have their shortcomings, they are widely used to make predictions on almost all things relating to elections or public policy.

With AdWords Scripts, there are things you should do and there are things you can do. I’m not sure where on the spectrum the topic for this post falls, but let’s put on our mad scientist hats and create a way to leverage political polling data in our AdWords campaigns.

You might never want to do something like this, but along the way, we will walk through some more generic techniques and the pitfalls of creating wrappers for external API calls. (Don’t worry if these terms aren’t familiar — I’ll explain later.) This will keep our code clean, not to mention easy to share and reuse. So even if you never plan on utilizing political data in your campaigns, you will be able to apply these techniques to an external data API that is important to your business.

The API we are going to use to find this data is the Huffpost Pollster API. This set of free web services will provide us with the latest political polling data so we can incorporate it into our scripts.

Learning About the Candidates

One of the main advantages of AdWords Scripts is the ability to make calls to external data sources (or URLs) using the URLFetchApp. In the past, I’ve used this feature to incorporate data from the WeatherUnderground API, Salesforce API, Twilio API, and many others into my scripts.

Each of these sources provides an API (Application Program Interface) in the form of a set of URLs we can call to request data or perform actions. Sometimes, these URLs are referred to as endpoints.

When you visit Google or Amazon, you are making a request to those URLs (google.com and amazon.com), and they are sending back the page for your browser to display. In the case of these APIs, we are doing the exact same thing, but the data are being returned in a format that our AdWords Scripts code can easily work with.

That’s where an API Wrapper comes into play. A wrapper is simply a piece of reusable code you write to make interacting with an API easier on yourself and others. A good way to think about this is to imagine handing your wrapper code to someone else to use. How many questions would they need to ask you to get started? How much code would they need to write to use your wrapper? A good wrapper should need very little explanation.

It’s okay if this is still a little murky right now. It will become a little more concrete as we actually write the code.

The First 100 Days

It’s pretty rare that I start out with the intention of creating an API wrapper. Most of the time I start with a set of separate functions, all relating to the same API, that I refactor into a wrapper later.

The Pollster API is pretty straightforward, since it really only contains one endpoint and three methods (the Charts, Chart and Polls methods). Let’s start with making a call to the Charts method. The first function to interact with the Charts method would probably be a function like this:

First, we build a request URL (just like the URLs in your browser) based on the parameters the method accepts. Then we make a request to that URL using URLFetchApp.fetch() and return the parsed response that they send back.

Despite the lack of error checking, this function gets the job done for the Charts method. Let’s move on to the Chart method. The steps are remarkably similar: Build the request URL from the parameters, make the request to the URL, then parse and return the results. It’s so similar that a good place to start would be to copy the first method and make a few updates, which is exactly what this is:

Now we have two functions with similar logic accessing the same API. It’s probably a good idea at this point to start thinking about creating a wrapper.

Bringing The Party Together

In JavaScript, one way to group related code and properties together is to create an Object. This isn’t a programming course, so I won’t get into the details about object-based design. All you really need to know is that an Object in your code should represent a thing (and all the stuff of or relating to that thing). In our case, the thing is the Pollster API, and so our Object is going to contain all the stuff relating to it.

Since we already have some of the functions that will be going into our Object, all we need to do is wrap them in what is known as a constructor function. It’s called that because we will call this function later to “construct” a new API object.

You will notice that we needed to change the definition line of our two functions getChart and getCharts. That’s because those functions are now considered methods of the HuffpostPollsterAPI object we just created. A method is simply a function that is assigned to a property of an object.

Constructors, methods, properties?! Ok, so the lingo can get a little confusing, but we don’t need to focus on that. The important thing is that all the logic for interacting with the API is “wrapped” inside our new Object. Any code in our main function can simply create a new instance of the HuffpostPollsterAPI Object and then call the getCharts and getChart functions. There’s no need to understand all the details of interacting with the API.

While we’re here, let’s go ahead and add the third and final method to this Object to call the Polls method of the API. I’ll give you a hint: The steps are incredibly similar to calling the Charts method.

Now, that is some ugly code, but it works. Remember that the main purpose of this wrapper is to simplify our main application code so that it’s really easy to call the data from this API. Since almost all the parameters to the methods are optional, how would someone call the getPolls API with just a topic? Sounds like a lot of explaining to me, so let’s make it a little easier for them.

Trim Those Earmarks

One way to handle this problem is to pass a configuration object (or sometimes a parameter object) to the method that contains the original arguments as its properties. It sounds confusing, but you’ve probably seen it used before without realizing it. Here’s what our code looks like after making the change:

Because I am sending config objects to the getCharts and getPolls functions, I can generalize the processing of those objects into a separate function called buildQueryString to make my code a little cleaner.

Wait, why are we back to the original definition syntax for this new query string function? Because that code is really only useful to me inside the API object. Someone using my object doesn’t need to use it or even know it exists. Using the original syntax makes this function “private” in the sense that it is only available to the code inside the API object. The general practice to distinguish between public methods (available outside the object) and private functions is to begin all private functions with an underscore.

The code is looking a lot better now, but there are still some things we can clean up. Here’s the final version of the HuffpostPollsterAPI.

Now we have our wrapper, so let’s put it to work.

Bid Multipliers By Popularity

Our new wrapper allows us to find the current polling data for each candidate as soon as it is available on the Pollster API.

After exploring the API a little bit, I found that there were a few things to think about before using these data in a campaign. The first one is the source of the data. Different sources have different polling methods, biases and questions. If I’m going to run this for a few months, I want to make sure I’m using a consistent source of data.

Next, I wanted to make sure I was using the most recent data. Polls take time to run, so they aren’t as frequent as some other sources of data. I only wanted the most recent data from the source I selected.

Of course, this is a contrived example that should only be used to illustrate some of the functionality. After grabbing the most recent primary polling data, the code looks for campaign labels for each candidate and sets the bid multiplier for the desktop accordingly.

Conclusion

If you made it this far, congratulations! We were able to build a complete API Wrapper that can now be reused in multiple scripts and shared with anyone you want. We learned about when it makes sense to group code into Objects and how to refactor that code to make it easier to use.

As I mentioned at the start of this post, I’m pretty sure managing your marketing campaigns using political polling data falls into the mad scientist category, but you never know until you try.

The post Use External Data In Your AdWords Campaigns With Scripts To Call APIs appeared first on Search Engine Land.