How to use the Google AdWords API to automate AdWords.

You run an AdWords agency. You’re thinking about building an AdWords tool using the AdWords API.

 - You might want it to make your agency more efficient. You’ve outgrown your duct-taped together collection of scripts, spreadsheets and rules. You want to spend less time on drudge work and more time on strategic value-add tasks. Maybe you want to grow without hiring.

 - You might want a second income stream. Selling an AdWords tool takes a lot of stress off relying on client work. Even more so if you charge a regular monthly subscription. It’s one of the few ways we have of growing our businesses that isn’t directly tied to our time.

Context: In this essay I’m going to use the word app to describe your custom-built AdWords tool.

Finding a developer.

Unless you’re lucky enough to have a tame developer in the office, you’re going to have to find someone to build your app.

There are plenty of competent developers around. There are plenty of competent AdWords specialists about. The subset of competent developers who know AdWords is much smaller.

It's even smaller after you've filtered it down to people who -

  • can translate your ideas into a working app;
  • have learned to work around the AdWords API’s quirks;
  • and are not working for $XXXK a year at a major agency.

You might be tempted to recruit a developer from a freelancing marketplace. Sites like upwork, fiverr etc make it look possible to hire a highly-skilled freelancer from a low-cost-of-living country for a handful of beans.

In practice, freelance marketplaces are markets for lemons.

Let me explain.

It is true that a competent developer might start her solo career on a freelancer site. Being a good developer doesn't automatically make you good at finding clients and these sites offer developers the promise of well-heeled clients from high-cost-of-living countries.

The client can't tell the difference between a competent developer and an idiot at the time of hiring. The risk of failure gets priced in to what the client will pay. That drives rates down.

Any developer who is capable of meeting your technical specs and communicating professionally eventually realises that they're working for peanuts.

So they leave, and the average skill level goes down.

That leads to a worse experience for the clients who in turn lower what they’re prepared to pay or stop hiring on these sites.

So the site ends up full of inexperienced buyers hoping to get their project built for $27, and a bunch of desperate developers who promise the world, deliver junk and have the communication skills of a turnip.

(Freelancer marketplace sites being a market for lemons inspired by tweets by @patio11.)

You don’t want your app to be built by someone you end up hating. Reasons for this will be clear later.

Don't get stranded in the assumption zone.

The next biggest risk, after hiring, is that your developer won't understand exactly what you want before they start work. It is not a given that your developer can read minds.

The assumption zone is where your assumptions about the project are different to the developer's assumptions about the project.

It can take several weeks of programming before your app is sufficiently complete to know that there is a problem.

You rightly won’t want to pay for wasted effort or re-work, and your developer rightly won’t want to work for free.

The rest of this essay is a list of things that I've bumped into over the years that trip people up when building AdWords tools using the AdWords API. The list is in no particular order.

Context: I’m writing from the point of view of building web apps. Much of this essay is also relevant if your app is installed software or a mobile phone app.

A web app is a program that runs in your web browser (Chrome, Safari, Firefox etc) instead of being downloaded and run from your computer.

The regular AdWords interface at www.adwords.google.com is a web app. AdWords Editor is installed software.

Hosting.

Your app will need to be hosted somewhere. Shared hosting or a cheapish reseller hosting account probably won’t work. You’ll want to check this with your developer.

An app for internal use won’t need much in the way of hosting - a $10/month Amazon Web Services EC2 instance might be enough.

If you’re building an app for the world to use it’ll need hosting hefty enough to handle the traffic, processing and storage requirements.

SSL certificate.

Your app should use the secure HTTPS protocol rather than the insecure HTTP protocol. You’ll need a SSL certificate for this.

These range in price from free from Let’s Encrypt to a couple of hundred dollars a year.

Installing and updating the certificate is a painful manual process at some hosting providers. At other providers it's a one-click install with automatic renewal.

Backups.

You need to back up:

  • The computer code that makes up your app.

  • The data your app generates.


An automated system is best. It should back up periodically and delete older backups. For example, you might want to back up once a day and keep the daily backups for 30 days.

Backing up is only half the process. You also need a way of verifying that the backups worked and know how to restore from backup.

I don’t have to tell you that AdWords generates a lot of data. I bumped into a problem where an app I built stored daily performance reports from a few hundred campaigns. It worked fine at first but eventually the database got so big that the backup program couldn't finish.

Think about what AdWords data your app has to store and for how long it must be kept.

Automated testing.

Some developers write automated tests to check that the code they wrote - your app. They’ll refer to these tests as unit tests and integration tests. The difference is irrelevant for your purposes.

Automated tests do the same job as having a human click every button or link in your app to make sure it's working as expected. The difference is that testing programatically takes only seconds.

Having a comprehensive test suite makes it much faster and safer to update or alter the app later. But, writing these tests takes time (aka money).

Reducing the number of tests is a common compromise if the budget is tight or if you're building a limited first version.

This compromise isn't always right for AdWords apps because the computer code your app uses to interact with Google has to be updated frequently. More on this later.

Automated testing doesn’t usually include checking that external services are working. You should make an exception and have your developer write tests to ensure that you’re getting good data from Google, and that changes you make via your app work.

Security.

Your app will wrangle commercially sensitive data. That data must be safe from unauthorised access or modification.

The best way to ensure security at a reasonable price is to use a web app development framework.

A framework - Laravel or Ruby on Rails are popular - is a set of pre-written computer code for handling features that most web apps need.

If your developer uses a framework you won't have to pay to reinvent wheels like checking a form for valid input or making sure only an authorised user can pause a campaign.

A good framework includes computer code to lower the risk of a security breach. Using a framework is infinitely more secure than hoping your chosen developer is both an expert in AdWords and a top-notch security professional.

Your developer will need credentials like usernames and passwords while developing. You should ask your developer to give you a list of places where credentials are stored, and instructions on how to change them.

You should revoke the developer’s credentials once they no longer need them. You’re not doing this to be malicious or because you’re distrust them, but because it’s the right thing to do.

User authentication.

Your app will need a way for people to register, log in, log out and reset their passwords.

Again, a framework will do most of the heavy lifting, but don't assume that your developer knows that they are to build it.

Authorization.

If you’re building an app for the public, you’ll need to make sure that each user can only access their data, not other user’s.

This may also be applicable if your agency assigns clients to individual staff members.

Error handling.

I don’t have to spell out how uncomfortable things could get if you paused a campaign or dropped the daily budget by half in your app but something went wrong and those changes weren’t made in AdWords.

These kinds of communication errors between your app and AdWords do happen. We’ll talk more about why in the rates limit section later.

You’ll need to think about how you want to your app to respond when something goes wrong. You might choose to have the app retry a few times, or to display a message on screen, or to send an email etc.

Compliance with data protection laws.

If your app is open to the public, or you do remarketing you’ll probably need to follow local data protection requirements.

At the very least you’ll need a privacy page because you can’t get an OAuth token without one. You need an OAuth token to let Google know that it’s OK to let your app connect to your AdWords account. (More on this later.)

What happens the first time someone uses your app?

If you're building an internal app for your agency you could get away with a fumbling first time. If you're building an app for the public it must offer a great first experience.

You have a pretty good idea of what your app will look like once it’s got your campaigns, ad groups, keywords etc in it. But, what does it look like empty?

The first run flow will usually be different from the way the app is used every day. What happens after your user hits the register button?

I’ll show you how to communicate your expectations to your developer a little later. But, first, here is a list of things that are not common knowledge about the Google AdWords API that trip people up.

You need approval to use the AdWords API.

Google requires that you apply for an AdWords API developer token before you can use their API. You should apply as early as possible because not getting approval is a deal breaker.

Apply for your token from your main manager account (aka MCC). That'll give your app access to the manager and client accounts under it without having to authorise each account.

More information on the application and approval process here.

You may have to prove that your app can connect to AdWords and process data before you get final approval. You should allow some contingency time and budget for your developer to write code to demonstrate this.

Anecdotally it’s easier to get approval for basic access than it is for standard access. (See section on rate limits for the difference between basic and standard access.)

The API can’t do everything.

There are some things that you can do in your AdWords account that you can’t do using the API. Make sure that the API supports your intended use.

Required minimum functionality.

Ignore this if you’re building an app for internal use only.

If you’re building an app that your clients or the public can use you need to meet the required minimum functionality requirements.

These requirements specify what your app has to be able to do. For instance, if your app does keyword research it also has to allow your users build campaigns, manage them and get reports.

You’ll find the requirements here.

Google sunsets the AdWords API.

That's geek speak for "You have to update your app or it won't work". At the time of writing every API version lasts approximately nine months.

It's impossible to say how long these updates take because that depends on what your app does, and if Google has made significant changes to the parts of AdWords your app interacts with.

This is where a good relationship with your developer and a robust test suite come in. Your developer can make the necessary changes, run the tests and be confident that everything works.

Read more about the sunset and deprecation schedule here.

Daily rate limits.

Google offers two levels of API access - basic and standard.

Basic access has hard limits on the number of times your app can get reports and data from AdWords and send changes to AdWords. In practice, these limits are high enough for many apps.

If you need to access the API more often you can apply for standard access which has no limits.

More information on rate limits here.

On-the-fly rate limits.

On-the-fly rate limits apply to all apps, whether they have basic or standard access.

Google prevents people overwhelming the API by limiting the frequency at which your app can make requests - get data or send changes.

Dealing with Google's on-the-fly rate limits is more complicated than it is with many of the other APIs your developer might know.

This is because:

  • There are different rate limits for new accounts and older accounts. Older accounts can make more frequent requests than newer accounts. At the time of writing there is no solid definition of what an older account is.

  • There is no specification listing how many queries per second your app can make before it hits the limit.

  • It appears that the limit changes depending on how many other people are using the API.
  • There are different rate limits for each service.


If your app hits the limit the request gets rejected. You might have hit the pause campaign button in your app, but that campaign won't be paused in your AdWords account. Instead the API returns a rate exceeded error.

Dealing with this should be simple. The rate exceeded error message includes how many seconds you should wait before retrying. Your app should catch the error, extract the wait time, wait that many seconds and try again.

In practice it’s not. There appears to be no guarantee that waiting the required time will result in a successful operation. The AdWords API developer forum is filled with unhappiness and clumsy workarounds.

Your app must do most of the work in the background.

Perhaps your app has a button to pause a campaign.

When you click the button your app sends an instruction to AdWords to pause the campaign. AdWords responds with "The campaign was paused". Your app changes the text on the button from “Pause campaign” to “Enable campaign”.

Your developer will know this process as the request -> response cycle.

The app will feel laggy if it takes more than a second or two for something to happen after you click the button.

You are unlikely to get sub-second responses from the AdWords API all the time. It might take a couple of minutes if your request hits a rate limit and has to retry.

You can keep your app feeling snappy by taking communication with AdWords out of the request -> response cycle.

When you click the “Pause campaign” button your app adds the instruction to AdWords to a job queue and then changes the button to “Enable campaign”. It feels quick and responsive.

The job is handled in the background, invisible to the user. It doesn't matter if it takes 5 seconds or 5 minutes.

Of course you need a way of detecting if something went wrong and telling the user about it. See the section on error handling above.

Keeping your app in sync with AdWords.

A human, a rule, automated bidding or a script can make changes to your AdWords account. If your app doesn’t have a way of becoming aware of these changes you could end up making decisions on stale out of sync data in your app.

The best way of doing this depends on what data your app needs and what it does. I’m always happy to speak geek with fellow AdWords people so hit me up if you’d like to talk about this.

What technology are you going to use?

Unless you have deep experience you should leave the choice of technology to your developer, subject to a few caveats:

  1. Google provides code libraries - pre written computer code in several computer languages: Java, .NET, PHP, PERL, Python and Ruby. Using these will make the initial development and future maintenance faster and cheaper. Your developer should have to work incredibly hard to convince you not to use one of these languages.

  2. Many developers like to use the latest bleeding-edge hot language or framework. This is not always in your best interest. If you build you app on solid proven technology the quirks and errors have been ironed out; there is a bigger pool of people with appropriate skills and experience and the technology is likely to be supported for a few years.


Frameworks like Laravel (PHP language) or Ruby on Rails (Ruby language) are safe bets if your app is web-based.

Customer support.

Ignore this if you’re building an app for internal use only.

Some people who profess to be AdWords experts know very little. You may have audited an AdWords account that looked like a gorilla managed it. You ain’t seen nothing yet.

You haven’t scraped the dregs off the bottom of the incompetence barrel till you’ve run a public AdWords app.

You’ll need to think about the cost of:

  • Producing training/support materials.

  • Handling support requests.

  • Making the app bulletproof to prevent crazy "Why on earth would anyone do that?" errors.


The bus factor.

The bus factor is a measurement of the risk resulting from information and capabilities not being shared among team members, from the phrase "in case they get hit by a bus".

Wikipedia

If you’ve hired a lone developer you’ve got a bus factor of one. Hiring a development shop might reduce this risk.

You should do the following to mitigate this risk no matter who you hire.

Store the code on Github.

If the computer code that makes up your app exists only on your developer’s laptop you’re vulnerable.

You can get rid of this vulnerability by having your developer use Github to store the computer code. Most developers will be familiar with it.

You should set up an account on Github and set up a repository for your app in your account. You then invite your developer to collaborate so they have the access they need.

If you don't know how to do this you should have your developer walk you through the process.

When I'm developing apps I push my work to Github at the end of the day. That way my client can continue developing the app if I get hit by that bus.

Own your OAuth credentials.

Your OAuth credentials allow users of your app to tell Google it’s OK for you app to access their AdWords account. You should set these up in your account even if you have your developer guide you through the process.

Own your developer token.

If you apply for this via your main AdWords manager account you’ll have taken care of this.

How to start an AdWords API project.

Grab a pencil and paper. Draw every screen you think your app will need. These are called wireframes.

Don't get bogged down in details like colours, gradients, fonts etc. Keep this low-fidelity but include every link and button, and examples of the data you’ll want to show.

If your app has a screen that shows low CTR keywords and you want to show the parent ad group and campaign you should include that on your sketch. This will tell your developer that they need to get the ad group and campaign name when they get the keyword.

These wireframes will help you fly over the assumption zone.

After you've drawn the wireframes you should describe what each button and link does.

Links are pretty easy because they’re normally used for moving around the app. Something like “Click the Dashboard link and see the Dashboard view” is enough.

Buttons are a more complicated because you need to be explicit about what happens when they’re clicked.

For instance you might have a "Generate report" button. Your description could read:

When the user clicks the "Generate report" button

  • If there were no conversions during the last 7 days, send the no conversion email template to the client.
  • If there were conversions, send the regular conversion report. Format the report as a PDF and send it to the client’s primary email address. CC copies to the client’s other reporting email address.
  • If any of the email addresses bounce, send a bounce email warning to me.
  • Keep the user on the same screen. Show a confirmation message and disable the report button so the user can't send more than one report a week.

This detail is gold to a developer and it will save you money. The quote (estimate) to build your app is going to be much higher if your developer has to pad their price to cover a bunch of uncertainties.

It’s cheaper and easier to stop a user sending more than one report a week when it’s built into the system from the beginning. Even simple requirements can cost lots more if they have to be bolted on later.

There is another reason for wire framing: Google may want to see designs before they approve your developer token. It’s been my experience that wireframes plus a detailed description of what the app will do is often enough to get approval for basic access.

Aside: If you don’t want to use a pencil and paper, use Balsamiq to draw your wireframes.

What next?

Want to talk about some aspect of the API or this essay? Email me (me@pete-bowen.com) for a no-cost, no-obligation chat. I’m always happy to talk AdWords and code.

If you’re looking for a developer I may be a good fit for you.

We’ll start with a road mapping session. This takes 2-3 hours, usually over two sessions Skype/Hangouts/Zoom etc.

The road mapping session is an investment in risk reduction.

At this stage the biggest risks that your AdWords API app development project faces are:

  • Doing something that Google doesn’t approve of and being dead in the water before you start.
  • Needing an API feature that’s not available, and for which there are no workarounds. Again, dead in the water.
  • Getting stuck in the assumption zone. If you and your developer are not on the same page building your app will degenerate into a death march for both of you.

At the end of the road mapping session you’ll be confident that your app is technically possible and complies with Google’s requirements. You’ll have a solid set of wireframes and requirements with which to brief your developer. (Me or someone else). You’ll know exactly what the next step is.

If you'd like, I will give you a fixed price offer to build your AdWords API app after the road mapping session. You won't have to worry about nasty surprise costs or arguments about what was included and what is extra. Otherwise, you're welcome to use any developer you like.

Lets start with a no-cost, no-obligation chat. Email me (me@pete-bowen.com) and we'll arrange to meet online.


Other articles you might find useful:

Watch your back for centaurs.

Centaurs - human+computer teams will outperform and replace AdWords agencies that rely on human power alone. Here are four ways to enhance your AdWords powers with automation.


© Peter Bowen 2018 | Isle of Wight

v2.0

Login