Building custom tools with the Google Ads API.

You run an digital marketing agency. You’re thinking about building a custom Google Ads tool using the 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 Google Ads 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.

In this essay I'll share some things that I've seen sink custom Google Ads tool projects and then show you how to get started.

Think about these things before you start, or you will suffer later.

I've seen too many people's hopes crushed by avoidable mistakes when building custom Google Ads tools using the API. You must be aware of these issues or you'll waste time and money (possibly lots of both).

1. Finding a developer.
2. Don't get bogged down in the assumption swamp.
3. Hosting.
4. SSL certificate.
5. Backups
6. Automated testing
7. Security.
8. User authentication.
9. Authorization
10. Error handling.
11. Compliance with data protection laws.
12. What happens the first time someone uses your app?
13. You need approval to use the Google Ads API.
14. The API can’t do everything.
15. Google sunsets the API.
16. Daily rate limits.
17. On-the-fly rate limits.
18. Your app must do most of the work in the background.
19. Keeping your app in sync with your Google Ads account.
20. What technology are you going to use?
21. Customer support.
22. The bus factor.

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 Google Ads specialists about. The subset of competent developers who know Google Ads 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 Google Ads API’s quirks;
• and are not working for $XXX XXX 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 rich countries.

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

Any developer who can of meet your technical specs and communicate professionally eventually realises that they're working for peanuts.

So they leave, and the average skill level available in the freelance marketplace goes down.

That leads to a worse experience for the clients. They then lower what they’re prepared to pay, or stop hiring via these sites.

So the site ends up full of:

• inexperienced clients 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 bogged down in the assumption swamp.

The next biggest risk, after hiring, is that your developer won't understand exactly what you want before they start work. She can't read your mind.

The assumption swamp: You assume somethings about the project. The developer has different assumptions.

It can take week or months of programming before your app is sufficiently complete to discover that you're armpit-deep in the swamp.

What you see on the demo server is nothing like what you had in mind. You've asked for a motorbike, your developer thinks you wanted a tractor, and has already built the engine and 4 wheels.

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

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 Google Ads 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 Google Ads data your app has to store and for how long it must be kept. Sometimes it's better to get rid of old data rather than hanging on to it.

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 this discussion.)

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 Google Ads 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 Google Ads 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 Google Ads.

These kinds of communication errors between your app and Google Ads 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 Google Ads 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 or they won't give your app a propper try.

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?

You need approval to use the Google Ads API.

Google requires that you apply for an Google Ads 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 account and client accounts under it without having to authorise each account.

You may have to prove that your app can connect to Google Ads 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 Google Ads 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 may 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 Ads 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 it will take to update your app because that depends on what your app does, and if Google has made significant changes to the parts of Google Ads 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 Google Ads and send changes to Google Ads. 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.
 Keyword research seems to have a particularly tight rate limit.

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 Google Ads 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 Google Ads 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 Google Ads to pause the campaign. Google Ads 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 Google Ads 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 Google Ads out of the request -> response cycle.

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

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 your Google Ads account.

A human, a rule, automated bidding or a script can make changes to your Google Ads account. If your app doesn’t have a way of learning about these changes it could end up basing decisions on stale out of sync data.

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 Google Ads 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:

• 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.


• 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 Google Ads experts know very little. Ever audit an 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 Google Ads 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.

From Wikipedia...

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".

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 Google Ads 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 Google Ads manager account you’ll have taken care of this.

How to start an Google Ads 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 kind of 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.

Even simple requirements can cost lots more if they have to be bolted on after the project is almost done.

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.)

Want to increase your conversion rate?

I’ve seen conversion rates double, triple and even 10X after a few quick and easy changes to the enquiry form. Subscribe now, and I'll send you a free copy of my in-depth ebook High-Converting Enquiry Forms.

You're already paying for clicks. Now turn them into conversions. Privacy policy. Unsubscribe at any time.