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.

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 Service account

Service account setup

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 under APIs & Services.
   1. If it isn’t, click + Enable APIs and services and enable the Ads Data Hub API.
3. In the left navigation menu, click IAM & Admin > Service Accounts.
   1. If you haven't yet created a service account, create one.
4. Click the 3-dot menu () under "Actions", then click Manage keys.
   1. Click Add key > Create new key
   2. After ensuring that "JSON" is selected, click Create.
5. Add the service account email address as a user in your Ads Data Hub account.

Send a sample request

#!/usr/bin/env python3

"""This sample shows how to retrieve all accounts associated with the user.
"""
import json
from google.oauth2.service_account import Credentials
from googleapiclient.discovery import build

SCOPES = ['https://www.googleapis.com/auth/adsdatahub']
DISCOVERY_URL = 'https://adsdatahub.googleapis.com/$discovery/rest?version=v1'
creds = Credentials.from_service_account_file(
    'service-account.json').with_scopes(SCOPES)
developer_key = 'YOUR_DEVELOPER_KEY'  # Replace with your developer key.
service = build('AdsDataHub', 'v1', credentials=creds,
                developerKey=developer_key, discoveryServiceUrl=DISCOVERY_URL)

# Replace with your ADH account ID.
adh_account_id = input('ADH account ID (e.g. "customers/123456789"): ').strip()
queries = service.customers().analysisQueries().list(
    parent=adh_account_id).execute()
print(json.dumps(queries, sort_keys=True, indent=4))

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:
  • Poll query operation status.
  • Use a BigQuery client library to retrieve completed query results.
• Contact ADH support if you have questions or feedback about the API.