Google Ads reporting Python — Step by Step Guide

Google Adwords user interface is great and keeps being updating to be more user-friendly. Its UI features don’t always allow you to solve problems unique to your business. I was inspired by a question from SEM team that they would like to have ads spend report by hour of day.

Definitely, hourly ads spend reports can be created via Adwords UI but it takes extra resource from your team to pull the raw data and generate reports specially when you have multiple accounts. The internal database records daily data of adwords but not for hour of day. Thus, let’s leverage Adwords API!

There are several Adwords API client libraries, like PHP, Ruby, Java, etc. I settled on the Python Library because I don’t have any experience of using other languages. (Sometimes, I hope I could have some working experience as a web/software developer… LOL).

Make API call via OAuth2.

If you are a beginner to Adwords API and also don’t have an adwords account , I would recommend to follow the official guide and videos (five episodes). Because you need to create a test account in order to play around Adwords APIs, the official guide & videos will walk you through making the first API call.

Let’s start our journey if you have adwords accounts. In short, two scripts are needed: 1. first script — to get a refreshed token 2. second script — get ads spend by hour of day on campaign level.

No worries if you have never used Adwords API before. The next part will walk you through the very beginning.

Steps:

1. Set up authentication via OAuth2
2. Request/Get a developer token for your adwords account
3. Get your refreshed token and configure your adwords client — run script ‘get your refreshed token’
4. Make your API call — run script ‘ Get_ads_KPIs_HourOfDay.py’

Now let’s go through all details within each step.

1. Set up authentication via OAuth2

Goal of this step: get client id and client secret. Those are your app credentials. You will have those after created your own app on Google APIs Center.

First of all, create an app at Google API center which can be create via this link (https://console.developers.google.com). Please use the same email that you used to access adwords account.

Open the Google API Console Credentials page. Click ‘Select a project’ > ‘NEW PROJECT’ > enter a name for the project > ‘Create’.

Once your project has been created then click ‘Create credentials’ and choose ‘OAuth client ID’.

pic-1

pic-2

pic-3

Please download or copy & paste your client ID and client secret, and save them in a safe place :).

Once you click the ‘OK’ in the pic-3. You will see the similar page as the screenshot below (Pic-1). For example, in pic-1 my app name is ‘Ads-api’ and the client ID can be seen.

pic-4

2. Get/Request a developer token

Go to your adwords account click ‘Tools’ icon on the right side of the corner and click ‘ API Center’. Then you will land on a similar page as P2 showing. Basic access level is enough for you to make API call. Copy and paste developer token info into your ‘googleleads.yaml’ — where you store your credentials to access your adwords account.

pic-2

pic-3

3. Get your refreshed token and configure your adwords client

Add your Client ID and Client Secret that you get during the step 1 into the script below. Then run script below ‘Get_your_refreshed_token.py’ via your terminal (Mac user) or comment line (PC user). Since I am a Mac user, I will use terminal to address the rest of the steps.

You will see the screenshot below while running ‘Get_your_refreshed_token.py’

pic-5

As the instruction puts in the pic-5, copy & paste the URL from the terminal into your browser. It might ask you to choose a gmail account. Remember to select your email which associated with your adwords account. Then you will see:

pic-5

You might see different name in pic-5. For example, my app name is ‘Adwords-test’. So you will see your app name there.Click ‘Allow’, then land on:

pic-6

Click ‘Allow’ again, then you will see:

pic-7

As the instruction shown on the webpage, copy code back to your terminal and hit ‘enter’ or ‘return’ on your keyboard. Then the terminal will show:

pic-8

Copy & paste the refreshed token and save it. So far so good? I know first time it might be still confusing but you already have the all parts to build the key to access adwords via API.

Let’s download “googleleads.yaml” (which store your credentials to access account)from Google API Python Library.

In the “googleleads.yaml”, there are two configurations. You only need one of them depending on your adwords account type. In my case, I am using AdWordsClient configurations. Now input those information that you’ve already got into the ‘googleleads.yaml’ file:

developer_token (from step 2)

client_id & client_secret (from step 1)

refresh_token (from step 3)

Save ‘googleleads.yaml’ file in a safe place on your local drive while completed those information below. Perfect! You completed setup the key to access the Adword!

4. Make your API call — run script ‘ get hourly ad spent’

run script “Get_ads_KPIs_HourOfDay.py” — which generate the csv file for each adwords account including last 4 weeks data.

Notes:

1. When initialize client object. adwords_client = adwords.AdWordsClient.LoadFromStorage(‘…/googleads.yaml’) Here the ‘googleads.yaml’ file including your credentials.
2. Be careful about the micro amount in API reporting. In order to get USD, monetary variables/1000000. In my script, I did this for ‘cost’ variable. df[‘Cost’]=df.Cost/1000000
3. I put three adwords account information in the dictionary (Ad_acc)just as an example to run reporting for several accounts at the same time. If you only have one account, then just input one account into the dictionary (Ad_acc). Or you can just input your brand name as the ‘key’ and adwords account ID as ‘acc_id’ as input variables into the function (run_Hour0fDay_kip_report)
4. I used functions to generate start date and end date for last 28 days based on today’s date. But you don’t really need that part. Just input any start/end date format as yyymmdd.
5. In my function (run_Hour0fDay_kip_report), the report definitions are created in AWQL (the AdWords Query Language). Report definitions can also be created in XML. Check the reference here.

Last, there are many different types of reports which can be built via AdWords API. Kindly check the reference.