Get started with the Ads Data Hub API

  • The Ads Data Hub REST API allows you to view Ads Data Hub customers, create queries, and run queries.

  • To use the Ads Data Hub API, ensure the user has the necessary Google Cloud permissions, enable the API in your project, manage permissions within Ads Data Hub, and optionally install a Google API client library.

  • You can authenticate and authorize API access using either OAuth 2.0 or a service account.

  • After setup and authentication, you can send sample requests to interact with the API, such as retrieving associated accounts.

  • Next steps include exploring sample queries, expanding on provided examples, and contacting support for assistance.

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.

Setup

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 serviceusage.services.enable permission in the Google Cloud project. The user with serviceusage.services.enable permission must also be allowlisted to access the API.
  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 email address or service 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. This ensures that the service account or end-user’s account has permission 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. An authorization flow provides you with the necessary permissions to interact with the API. You can authenticate using either OAuth 2.0 or a service account.

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 navigate to your admin project.
  2. Verify that the Ads Data Hub API is enabled for your project.
    1. 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:
    1. Select Other.
    2. Optionally, give the client a name.
    3. 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 "Credentials" page of the API console
  2. Ensure that your Admin project is selected in the dropdown in the upper navigation.
  3. Click the download icon next to your API key.

Send a sample request

Python

 """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. 
 """ 
 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. 
 'client_secrets.json' 
 , 
 scopes 
 = 
 [ 
 'https://www.googleapis.com/auth/adsdatahub' 
 ]) 
 appflow 
 . 
 run_local_server 
 () 
 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 
 )) 
 adh_account_id 
 = 
 input 
 ( 
 'ADH account ID (e.g. "customers/123456789"): ' 
 ) 
 . 
 strip 
 () 
 pprint 
 ( 
 service 
 . 
 customers 
 () 
 . 
 analysisQueries 
 () 
 . 
 list 
 ( 
 parent 
 = 
 adh_account_id 
 ) 
 . 
 execute 
 ()) 

Java

 /* 
 * 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 
 * 
 * http://www.apache.org/licenses/LICENSE-2.0 
 * 
 * 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. 
 */ 
 package 
  
 com.google.api.services.samples.adsdatahub.cmdline 
 ; 
 import 
  
 com.google.api.services.adsdatahub.v1.AdsDataHub 
 ; 
 import 
  
 com.google.api.services.adsdatahub.v1.model.Customer 
 ; 
 import 
  
 com.google.api.services.adsdatahub.v1.model.ListCustomersResponse 
 ; 
 import 
  
 java.io.IOException 
 ; 
 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">https://developers.google.com/ads-data-hub/reference/rest/v1/customers/list</a> 
 * for more details. 
 */ 
 public 
  
 class 
 ListCustomers 
  
 extends 
  
 BaseSample 
  
 { 
  
 @Override 
  
 public 
  
 String 
  
 getName 
 () 
  
 { 
  
 return 
  
 "List customers" 
 ; 
  
 } 
  
 @Override 
  
 public 
  
 String 
  
 getDescription 
 () 
  
 { 
  
 return 
  
 "Lists customers associated with the authorized user" 
 ; 
  
 } 
  
 @Override 
  
 public 
  
 void 
  
 execute 
 ( 
 AdsDataHub 
  
 client 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 String 
  
 pageToken 
  
 = 
  
 null 
 ; 
  
 boolean 
  
 noData 
  
 = 
  
 true 
 ; 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "========================================" 
 ); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Listing of customers associated with the authorized user:\n" 
 ); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "========================================" 
 ); 
  
 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.
Design a Mobile Site
View Site in Mobile | Classic
Share by: