The Ads Data Hub API – Hello World


August 3, 2020

Ads Data Hub (ADH) is a new privacy-safe environment that lets you execute SQL queries on Google’s event-level ad data as well as your own. Aside from executing these queries through the UI, ADH also allows for a programmatic approach to dealing with the data. This enables additional functionality such as listing and updating existing resources, automating queries (scheduling), and similar. In this article, I will introduce the quickest path to execute your first ADH API call in Python.

Required Libraries

To execute ADH API calls you will need to install and import two libraries.

First, the google_auth_oauthlib which will control the authentication.

pip install google-auth-oauthlib

Second, the googleapiclient discovery library which will be used to create a service to communicate with the ADH API.

 
pip install google-api-python-client

Client Secrets and Service Account JSONs

To connect to any Google APIs, the requests need to be associated with a Google Cloud Platform project. From there you can monitor requests and quotas. You can create a client secret file in the Credentials section of your cloud console.

You may also want to generate a JSON key for a service account or use an existing one. This will allow you to authenticate as a service.

Authentication

There are two ways to authenticate the service to execute API calls. As a user, where you will be asked to authenticate with your Google account or using a service account.

User Authentication

from google_auth_oauthlib import flow
appflow = flow.InstalledAppFlow.from_client_secrets_file('client_secrets.json',
scopes=['https://www.googleapis.com/auth/adsdatahub'])

appflow.run_console()
credentials = appflow.credentials

*Credentials value is not stored and you will be asked to re-authorize every time you run the script. To avoid this, you can store the credentials token in a more permanent form. Make sure not to accidentally share the credentials file.

Service Account Authentication

from google.oauth2 import service_account
credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)

*Applications running in Google Cloud Platform can use default credentials provided by the environment they run in

Create a Service

To create a service you will first need to acquire a developer key. A developer key is available in your Google Cloud Console. To access it, navigate to “APIs & Services” Credentials where you can create a new key or use an existing one.

As shown below, to execute the build function you will need to provide the API name (AdsDataHub), its version (v1), the credentials and the developer key.

from googleapiclient.discovery import build
service = build('AdsDataHub', 'v1', credentials=credentials, developerKey=developer_key)

Once the service is created, you can start executing API calls under the email address obtained by the credentials object.

Execute API Calls

In the example below, we’re printing a list of customers under the account that the user has access to. For additional API methods, refer to the documentation.

customer_list = service.customers().list().execute()

for customer in customer_list['customers']:
  print(customer.get("name"))

Extra step – Schedule a daily query

Different services within Google Cloud can make the API even more useful. Using Cloud Scheduler, we can create a daily job to execute our script at an HTTP endpoint or as a cloud function that gets triggered by a Cloud Pub/Sub message.

If you have any questions about using Ads Data Hub, we can help! Contact us to learn more. In the meantime, here are some helpful resources to review:

Ads Data Hub API Documentation

A Quick Intro to ADH

Five Ads Data Hub Queries to Get You Started