Get started with the Ads Data Hub API

This guide explains how to get started writing applications that use the Ads Data Hub REST API to interact with Ads Data Hub. The Ads Data Hub REST API allows you to view Ads Data Hub customers associated with your Google account, create queries, and run queries.


There are a few steps that you need to complete prior to using the Ads Data Hub API:

  1. Ensure that the user enabling the API is granted permission in the Google Cloud project.
    1. The user with permission must also be allowlisted to access the API. Contact support to add users to the allowlist.
  2. Enable the Ads Data Hub API in the Google Cloud project in which the client credentials or the service account were created. To enable the Ads Data Hub API for a project using the console:

    1. Go to the Cloud Console API Library.
    2. Select the project you want to use from the list of projects.
    3. Search for "Ads Data Hub API".
    4. On the API page, click ENABLE.
  3. Manage permissions:

    1. The account used to create the credentials must be added to Ads Data Hub with the appropriate permissions. For a service account this is the service account email address. For OAuth, this is the user's email address that provides the app with permissions. This ensures that the service account or end-user’s account has permissions to run queries in Ads Data Hub.
  4. (Recommended) Install a Google API client library:

    1. The Google API client libraries are available in several popular languages, and allow you to work with many Google APIs. While this isn’t required, the client libraries reduce the amount of code that you have to write, and make authentication simpler to set up.
Client Library Ads Data Hub samples
Google API Client Library for Java Java
Google API Client Library for Python

Authenticate and authorize

The Ads Data Hub API can access and change data in your Ads Data Hub customer account, so it needs to verify that you’re an authorized user. Because of this, before you start interacting with the Ads Data Hub API, you’ll need to walk through an authorization flow. This is designed to provide you with the necessary permissions to interact with the API. This is accomplished using the OAuth 2.0 protocol for authentication and authorization.

The Ads Data Hub API supports both installed application and web application authorization flows, but this tutorial will only cover the installed application flow.

OAuth 2.0 setup

The API supports both the installed application and web application flows, but for this example we’ll step through the installed application flow.

  1. Go to the Google API console and select your project.
  2. Verify that the Ads Data Hub API is enabled for your project. a. If it isn’t, click + Enable APIs and services to enable it.
  3. In the left navigation, click Credentials.
  4. Open the Create credentials drop-down menu and select OAuth client ID. On the following page:
    • Select Other.
    • Optionally, give the client a name.
    • Click Create.
  5. Click the download icon next to the credentials that you just created.

Get your API key

Your API key (also known as a developer key) is used for authentication in the Python code sample below. To obtain your API key:

  1. Go to the Google API console and select your project.
  2. Navigate to the Credentials page.
  3. Click the download icon next to your API key.

Send a sample request


"""This sample shows how to retrieve all accounts associated with the user.

For the program to execute successfully, ensure that you run it using Python 3.

from __future__ import print_function
import json
from google_auth_oauthlib import flow
from googleapiclient.discovery import build

appflow = flow.InstalledAppFlow.from_client_secrets_file(
    # Replace client_secrets.json with your own client secret file.
credentials = appflow.credentials
developer_key = input('Developer key: ').strip()
# For versions of the Google API Python client library prior to 2.0, the
# `static_discovery` parameter below should be removed.
service = build('AdsDataHub', 'v1', credentials=credentials,
                developerKey=developer_key, static_discovery=False)

def pprint(x):
  print(json.dumps(x, sort_keys=True, indent=4))

customer_name = input('Customer name (e.g. "customer/123"): ').strip()



 * Copyright (c) 2019 Google Inc.
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.


import java.util.List;

 * This sample illustrates how to retrieve all accounts associated to the user.
 * <p>See the <a href="customers.list reference
 * documentation"></a>
 * for more details.
public class ListCustomers extends BaseSample {

  public String getName() {
    return "List customers";

  public String getDescription() {
    return "Lists customers associated with the authorized user";

  public void execute(AdsDataHub client) throws IOException {
    String pageToken = null;
    boolean noData = true;

    System.out.printf("Listing of customers associated with the authorized user:\n");

    do {
      ListCustomersResponse response = client.customers().list().setPageToken(pageToken).execute();
      pageToken = response.getNextPageToken();
      List<Customer> customers = response.getCustomers();

      if (customers != null && customers.size() > 0) {
        noData = false;
        for (Customer customer : customers) {
          System.out.printf("* Customer id: %d\n", customer.getCustomerId());
          System.out.printf("\tCustomer name: %s\n", customer.getDisplayName());
    } while (pageToken != null);

    if (noData) {
      System.out.println("No customers were found associated with the authorized user.");


Next steps

  • See sample queries in Ads Data Hub for examples of queries you can create and run with the Ads Data Hub REST API.
  • Expand on the samples to familiarize yourself with the API and customize it for your use case. Then try to:
  • Contact ADH support if you have questions or feedback about the API.