Using Google Ads API with REST endpoints

Using Google Ads API with REST endpoints

If you are looking to build an API that interacts directly with the Google Ads platform and aren’t using one of the supported client libraries provided by Google which includes Java, C#, PHP, Python, and Ruby, then this post might be helpful to you. In our case we were using Javascript, building a NodeJS backend that was required to interact with the Google Ads Platform to do various different actions for our clients, such as getting and displaying information from all their campaigns to trickier ones like adding IP Addresses to the campaign’s IP block list. We will be going over how to do all this following along with Google’s own Quickstart documentation and better explain some of the more trickier parts.

First thing’s first, make sure you have the right accounts set up to go forth with all the API calls. We want to be using Test accounts as to not mess up any production data or live ads while we are testing and developing this API.

You will need one production Manager account to get your developer token from. So go ahead and create a Manager account if you don’t have one already and head over to the Settings — API Center to get your developer token. Note: You can use this developer token to interact with any other accounts, not only your own under your account.

You will also need a Test Manager account, which can be created here. I recommend using a separate email address for all your test accounts as to not get anything confused. Create a new Gmail if you have to, it helps a lot when you are going back and forth between your test accounts and production manager account that has the developer token from above.

Next, you will need to get an access token and refresh token. This part we will not cover as you are free to use whatever client library you would like. We use React so we went with this library. Using that we were able to get refresh token given the authorization code returned after successfully logging in to our account that has the test manager account. More information on OAuth here.

Logging in to your test manager account here is important as you can only interact with test accounts until your developer token is approved.

The first API call I make tests if I’ve gotten everything set up properly, For that we use customers:listAccessibleCustomers. This call will list all the accounts you have access to work with, given your developer token and access token. From there, you can parse out the Customer ID and use that for any other calls you’d like to make.

The following cURL request will get this result. Fill in the missing variables with your own from above.

curl -X GET \ https://googleads.googleapis.com/v1/customers:listAccessibleCustomers \ -H 'Authorization: Bearer {your-access-token-here}' \ -H 'developer-token: {your-developer-token-here}'

If you received a list of your customer accounts you are on the right track. Getting a little more into it, let’s grab all the campaigns listed under one of our customer accounts. For this we are going to use this cURL request:

curl -X POST \ https://googleads.googleapis.com/v1/customers/5509440813/googleAds:search \ -H 'Authorization: Bearer {your access token here}' \ -H 'Content-Type: application/json' \ -H 'developer-token: {your developer token}' \ -H 'login-customer-id: {customer manager account id, if under a manager account}' \ -d '{ "query": "SELECT campaign.id, campaign.name, campaign.status, campaign.serving_status FROM campaign" }'

The URL the request is hitting can be hit to retrieve most of the account’s information using the correct query. Here is an overview with some information on the query language used above. The query will be somewhat familiar to you if you are used to SQL queries. The only thing is you would need to know which fields you want to access from the right resource first, otherwise, you will get a vague error. Here is a link to the reference, this provides a list of all the available resources.

Note: login-customer-id is the test customer's manager account id. If the customer you are trying to access has a manager account it is required to provide this id in the headers as done so above. For testing purposes where you can only use a test manager account, that means for every call you make basically.

If you want to interact with the campaigns you have retrieved from above, the API calls are slightly different and require you to go through each available service and its defined proto file here — linked proto file to Campaign Service, to build your desired request up. Below is an example of a request to add an IP Address to a specific campaign’s IP blocklist.

curl -X POST \https://googleads.googleapis.com/v1/customers/{CUSTOMER_ID}/campaignCriteria:mutate \ -H 'Authorization: Bearer {your access token}' \ -H 'Content-Type: application/json' \ -H 'developer-token: {your developer token}' \ -H 'login-customer-id: {manager account id, if needed}' \ -d '{ "customer_id": "{CUSTOMER ID - ex: 1234567890}", "operations": [ { "create": { "campaign": "customers/{CUSTOMER_ID}/campaigns/{CAMPAIGN_ID}", "negative": "true", "ip_block": { "ip_address": "127.0.0.1" } } } ] }

Again the documentation for these are somewhat vague and this is a very specific example but you can use this to build a request for any other service using the provided api reference and proto file, it will follow the same format.

Going over this request: URL contains the Customer ID you are calling this action on — all digits without the dashes as shown in the console. Then the JSON — Again the customer ID the same as in the URL, operations : you can see a list of available operations in the service's proto file, in our case CampaignService includes create, update, and remove. campaignin the created object refers to the campaign's resource name which follows that format. negative in this case, is there because IP Block specifically requires it. And then the criteria we are acting on which is ip_block.

Wrapping it up, the Google Ads API is a bit of a struggle to work with especially if you are trying to use REST endpoints with JSON as they are largely undocumented and a lot of the work is going from one reference to the other to piece together what you need. For me it was the IP Blocking, I hope this provides some clarity for some people and puts them on the right track to do what they need with the Google Ads API.

When in doubt, the Google Ads API forum is actually pretty active with knowledgeable members of the team responding to most everyone’s questions in a day or two(in my experience). There is also a good amount of info already on there for some specific use cases.

Originally published at https://www.syntx.io on June 28, 2019.