This is legacy documentation, and may not be complete. To see the latest documentation, if you are a marketer, refer to the Marketers site. If you are a measurement partner, refer to the Measurement Partners site.
Stay organized with collections
Save and categorize content based on your preferences.
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:
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.
Select the project you want to use from the list of projects.
Search for "Ads Data Hub API".
On the API page, click ENABLE.
Manage permissions:
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.
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.
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.
Service account setup
Go to the Google API console and navigate to your admin project.
Verify that the Ads Data Hub API is enabled for your project under APIs &
Services.
If it isn’t, click + Enable APIs and services and enable the Ads
Data Hub API.
In the left navigation menu, click IAM & Admin > Service Accounts.
If you haven't yet created a service account,
create one.
Click the 3-dot menu (more_vert) under
"Actions", then click Manage keys.
Click Add key > Create new key
After ensuring that "JSON" is selected, click Create.
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."""importjsonfromgoogle.oauth2.service_accountimportCredentialsfromgoogleapiclient.discoveryimportbuildSCOPES=['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))
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-09-18 UTC."],[[["\u003cp\u003eThe Ads Data Hub REST API allows you to manage Ads Data Hub customers, create and run queries, and programmatically interact with Ads Data Hub.\u003c/p\u003e\n"],["\u003cp\u003eBefore using the API, you need to enable it, manage permissions for access, and optionally install a Google API client library for easier integration.\u003c/p\u003e\n"],["\u003cp\u003eAuthentication is essential and can be achieved through either OAuth 2.0 or a service account, ensuring secure access to your Ads Data Hub data.\u003c/p\u003e\n"],["\u003cp\u003eAfter setup and authentication, you can send requests to the API to perform actions like listing analysis queries, as demonstrated in the Python code example.\u003c/p\u003e\n"],["\u003cp\u003eFor further exploration, refer to sample queries, utilize client libraries for BigQuery integration, and contact ADH support for assistance.\u003c/p\u003e\n"]]],["To use the Ads Data Hub REST API, enable it in your Google Cloud project, ensuring the enabling user has the necessary permissions. Add the credential email/service account to Ads Data Hub with appropriate permissions. Install a Google API client library. Authenticate with OAuth 2.0 or a service account, generating a JSON key for the latter. Finally, use the client library to interact with the API, for instance, listing customer accounts and retrieving existing queries, as in the sample provided.\n"],null,["# Get started with the Ads Data Hub API\n\nThis 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.\n\nSetup\n-----\n\nThere are a few steps that you need to complete prior to using the Ads Data Hub API:\n\n1. 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.\n2. [Enable the Ads Data Hub API](https://cloud.google.com/apis/docs/getting-started#enabling_apis) in the Google Cloud project in which the [client credentials](https://cloud.google.com/docs/authentication/end-user#creating_your_client_credentials) or the [service account](https://cloud.google.com/docs/authentication/production) were created. To enable the Ads Data Hub API for a project using the console:\n 1. Go to the [Cloud Console API Library](https://console.cloud.google.com/apis/library).\n 2. Select the project you want to use from the list of projects.\n 3. Search for \"Ads Data Hub API\".\n 4. On the API page, click **ENABLE**.\n3. Manage permissions:\n 1. The email address or service account used to create the credentials must be added to Ads Data Hub with the [appropriate permissions](/ads-data-hub/guides/assign-access-by-role). 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.\n4. (Recommended) Install a [Google API client library](https://developers.google.com/api-client-library):\n 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.\n\n| Client Library | Ads Data Hub samples |\n|------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|\n| [Google API Client Library for Java](https://developers.google.com/api-client-library/java/) | [Java](/static/ads-data-hub/samples/sample-files/ads-data-hub-v1-java-examples.tar.gz) |\n| [Google API Client Library for Python](https://github.com/googleapis/google-api-python-client) | |\n\nAuthenticate and authorize\n--------------------------\n\nThe Ads Data Hub API can access and change data in your Ads Data Hub customer\naccount, so it needs to verify that you're an authorized user. Because of this,\nbefore you start interacting with the Ads Data Hub API, you'll need to walk\nthrough an authorization flow. An authorization flow provides you with the\nnecessary permissions to interact with the API. You can authenticate using\neither OAuth 2.0 or a service account. \nOAuth 2.0 Service account\n\n### Service account setup\n\n1. Go to the Google API console and navigate to your admin project.\n2. Verify that the Ads Data Hub API is enabled for your project under **APIs \\&\n Services** .\n 1. If it isn't, click **+ Enable APIs and services** and enable the Ads Data Hub API.\n3. In the left navigation menu, click **IAM \\& Admin** \\\u003e **Service Accounts** .\n 1. If you haven't yet created a service account, [create one](https://cloud.google.com/iam/docs/creating-managing-service-accounts).\n4. Click the 3-dot menu (more_vert) under \"Actions\", then click **Manage keys** .\n 1. Click **Add key** \\\u003e **Create new key**\n 2. After ensuring that \"JSON\" is selected, click **Create**.\n5. Add the service account email address as a user in your Ads Data Hub account.\n\nSend a sample request\n---------------------\n\n```python\n#!/usr/bin/env python3\n\n\"\"\"This sample shows how to retrieve all accounts associated with the user.\n\"\"\"\nimport json\nfrom google.oauth2.service_account import Credentials\nfrom googleapiclient.discovery import build\n\nSCOPES = ['https://www.googleapis.com/auth/adsdatahub']\nDISCOVERY_URL = 'https://adsdatahub.googleapis.com/$discovery/rest?version=v1'\ncreds = Credentials.from_service_account_file(\n 'service-account.json').with_scopes(SCOPES)\ndeveloper_key = 'YOUR_DEVELOPER_KEY' # Replace with your developer key.\nservice = build('AdsDataHub', 'v1', credentials=creds,\n developerKey=developer_key, discoveryServiceUrl=DISCOVERY_URL)\n\n# Replace with your ADH account ID.\nadh_account_id = input('ADH account ID (e.g. \"customers/123456789\"): ').strip()\nqueries = service.customers().analysisQueries().list(\n parent=adh_account_id).execute()\nprint(json.dumps(queries, sort_keys=True, indent=4))\n```\n\nNext steps\n----------\n\n- See [sample queries in Ads Data Hub](https://developers.google.com/ads-data-hub/samples/writing-queries) for examples of queries you can create and run with the Ads Data Hub REST API.\n- Expand on the samples to familiarize yourself with the API and customize it for your use case. Then try to:\n - Poll query operation status.\n - Use a [BigQuery client library](https://cloud.google.com/bigquery/docs/reference/libraries) to retrieve completed query results.\n- Contact ADH support if you have questions or feedback about the API."]]