Set up API access

AI-generated Key Takeaways

Accessing the Data Manager API requires a Google Cloud project and a Google Account with the necessary permissions.
The Data Manager API must be explicitly enabled in your Google Cloud project settings.
Authentication for the Data Manager API can be set up using various methods, including user accounts and service accounts, with Application Default Credentials recommended for automatic credential finding.
Setting up access involves configuring Google Auth Platform settings and potentially undergoing Google OAuth verification for user accounts accessing sensitive scopes.
After authentication, grant the operating account email access to the desired Destination, following specific instructions for Google Ads or Display & Video 360 accounts.
The final step involves setting up the SDK for your preferred programming language (REST, .NET, Java, Python, Node.js, PHP) by downloading, installing, and configuring the relevant libraries.

Here's how to set up access to the Data Manager API with an SDK or REST.

Prerequisites

Before you can use the Data API, make sure you have the following:

A Google Cloud project.
A Google Account that has the serviceusage.services.enable permission on your Google Cloud project, or has a role that includes that permission. For example, roles/owner and roles/serviceusage.serviceUsageAdmin both include the serviceusage.services.enable permission. To check your permissions, see View current access.

Enable the API

If you haven't already, enable the Data Manager API by clicking Enable the Data Manager API or follow the instructions to perform this step manually.

If you can't find the Data Manager API or Enable the Data Manager API fails, verify your Google Account meets the prerequisites.

Set up authentication

You can use any of the Authentication methods at Google besides API keys. We recommend reviewing how to Choose the right authentication method for your use case to decide which approach is appropriate for your use case.

Two common authentication methods are user accounts and service accounts:

User accounts: Represent people who interact with Google APIs and services directly.
Service accounts: Represent apps, not people, as the users. They let your apps manage authentication and authorization. For example, if an app needs to access Google Cloud resources.

Your integration can use Application Default Credentials (ADC) to automatically find credentials from the environment so you don't have to change the client code to authenticate.

Choose User account or Service account impersonation to set up ADC:

Here are the steps to authenticate with user account credentials:

Configure the Google Auth Platform settings for your project.

Important: Any Google Cloud app used to obtain user credentials for the Data Manager API scope must undergo Google OAuth verification to avoid an unverified UI screen for its users. Google OAuth verification isn't required for service accounts.
1. Open the Branding page in the Google Cloud Console.
2. Select your project.
3. Fill out the form and click Create.
Since the Data Manager API scope is a sensitive scope, the following steps are required:
1. Go to the Data Access settings for your project.
2. Click Add or remove scopes.
3. Check the box next to Data Manager API in the list of scopes, and click Update.
4. Click Save.
5. Go to Audience in the Google Cloud Console and update the Publishing status and User type. Learn more about these settings in Manage App Audience.
Click Create OAuth2 client to create an OAuth2 client in the project, or follow the instructions to create a Desktop OAuth2 client.

Create OAuth2 client
In the last step, click DOWNLOAD CLIENT CONFIGURATION and note the download location you choose.
Generate a local ADC file by running the following command. This command launches a web flow where you are prompted to login to the Google Account you're using with the API.

Replace PATH_TO_CLIENT_JSON with name of the JSON file you downloaded.
```
gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform" \
  --client-id-file="PATH_TO_CLIENT_JSON"
```
Confirm credentials are setup correctly using the following command. If successful, the command prints an access token to the console.
```
gcloud auth application-default print-access-token
```

To learn more about authentication and credentials for your app, see Authentication methods at Google and How Application Default Credentials works.

Set up operating account access

Grant the email associated with your user account access to the Destination.

If using a Google Ads or data partner account, follow the instructions to add the email of the user to the account.
If using a Display & Video 360 account, follow the instructions to add the email of the user to the account.

Set up the SDK for your programming language

On your local machine, install the SDK of your choice:

REST

Update the placeholders in the following sample, such as OPERATING_ACCOUNT_PRODUCT, OPERATING_ACCOUNT_ID, and AUDIENCE_ID, with the values for your account and destination.
Replace PROJECT_ID with the ID of your Google Cloud.

Copy the sample to the command line to send the request.

Remove the linkedAccount attribute of the entry in the destinations if you aren't accessing the operatingAccount using an established product link.

#!/bin/bash

# Uses gcloud to get an access token. If the Application Default
# Credentials aren't for a service account, the command that specifies
# --scopes fails. This sample falls back to the command without the
# --scopes argument.
DATA_MANAGER_ACCESS_TOKEN="$(gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/datamanager || \
  gcloud auth application-default print-access-token)"

# Fetches and prints the scope information for the access token. If you
# get scope-related errors when you send the request in the next step,
# verify that this output includes the Data Manager API scope:
#   https://www.googleapis.com/auth/datamanager
curl https://www.googleapis.com/oauth2/v1/tokeninfo?access_token="${DATA_MANAGER_ACCESS_TOKEN}"

# Sends the request.
curl -X POST "https://datamanager.googleapis.com/v1/audienceMembers:ingest" \
  --header "Authorization: Bearer ${DATA_MANAGER_ACCESS_TOKEN}" \
  --header "x-goog-user-project: PROJECT_ID" \
  --header "Content-Type: application/json" \
  --data @- <<EOF
{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },
      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },
      "linkedAccount": {
        "accountType": "LINKED_ACCOUNT_TYPE",
        "accountId": "LINKED_ACCOUNT_ID"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ],
  "audienceMembers": [
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
          },
          {
            "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
          },
          {
            "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
          },
          {
            "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
          },
          {
            "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
          },
          {
            "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
          }
        ]
      }
    }
  ],
  "consent": {
    "adUserData": "CONSENT_GRANTED",
    "adPersonalization": "CONSENT_GRANTED"
  },
  "encoding": "HEX",
  "termsOfService": {
    "customerMatchTermsOfServiceStatus": "ACCEPTED"
  },
  "validateOnly": true
}
EOF

.NET

Download and extract google-cloud-ads-datamanager-v1-csharp.tar.gz.
In your .NET project, declare a ProjectReference dependency on the Data Manager API library. Replace PATH_TO_CLIENT_LIBRARY with the location where you extracted the google-cloud-ads-datamanager-v1-csharp directory from google-cloud-ads-datamanager-v1-csharp.tar.gz.
```
<ProjectReference Include="PATH_TO_CLIENT_LIBRARY\Google.Ads.DataManager.V1\Google.Ads.DataManager.V1.csproj" />
```
Optional. Get the utility library and code samples.
1. Download and extract data-manager-dotnet.tar.gz.
2. In your .NET project, declare a ProjectReference dependency on the utility library. Replace PATH_TO_UTILITY_LIBRARY with the location where you extracted the data-manager-dotnet directory from data-manager-dotnet.tar.gz.
```
<ProjectReference Include="PATH_TO_UTILITY_LIBRARY\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />
```
3. To format data, use the Formatter utility in your .NET project.
4. Browse code samples in the samples subdirectory.
  
  To run the code samples, set the DATA_MANAGER_DOTNET_LIB environment variable to the location where you extracted the google-cloud-ads-datamanager-v1-csharp directory from google-cloud-ads-datamanager-v1-csharp.tar.gz.
```
export DATA_MANAGER_DOTNET_LIB="PATH_TO_CLIENT_LIBRARY"
```
  Change to the samples directory and use dotnet run to get the list of available samples.
```
dotnet run --framework net8.0
```
  Pass the --help argument when running a sample to print a usage statement with expected parameters.
```
dotnet run --framework net8.0 -- ingest-audience-members --help
```
  To help you get started with some sample data, use the file at samples/sampledata/audience_members_1.csv.

Java

Download and extract google-cloud-ads-datamanager-v1-java.tar.gz.
Navigate to the google-cloud-ads-datamanager-v1-java directory.
Run the following command to build and publish the library to your local Maven repository for use with Maven or Gradle.
```
./gradlew install
```

In your Java project, declare a dependency on the Data Manager API library.

Gradle:

implementation 'com.google.cloud:gapic-google-cloud-ads-datamanager-v1-java:0.1.3'

Maven:

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>gapic-google-cloud-ads-datamanager-v1-java</artifactId>
  <version>0.1.3</version>
</dependency>

Optional. Get the utility library and code samples.
1. Clone the GitHub repository.
```
git clone https://github.com/googleads/data-manager-java.git
```
2. Navigate to the data-manager-java directory.
3. Build and publish the utility library to your local Maven repository.
```
./gradlew data-manager-util:install
```
4. In your Java project, declare a dependency on the utility library.
  
  Gradle:
```
implementation 'com.google.api-ads:data-manager-util:0.1.0'
```
  Maven:
```
<dependency>
   <groupId>com.google.api-ads</groupId>
   <artifactId>data-manager-util</artifactId>
   <version>0.1.0</version>
</dependency>
```
5. To format and encrypt the data, use the UserDataFormatter and Encrypter utilities in your Java project.
6. Browse code samples in the data-manager-samples subdirectory or on GitHub. To run a sample from the command line, use the Gradle run task.
  
  For example, the following command runs the IngestAudienceMembers sample and prints a usage statement:
```
./gradlew data-manager-samples:run \
  --args='IngestAudienceMembers --help'
```
  To help you get started with some sample data, use the file at data-manager-samples/src/main/resources/sampledata/audience_members_1.csv.

Python

Download ads-datamanager-v1-py.tar.gz.
Navigate to the directory of the download.
Run the following command to build the library and make it available to other projects in the same Python environment:
```
pip install ./ads-datamanager-v1-py.tar.gz
```
In your Python project, declare a dependency on the Data Manager API library. For example, if using a requirements.txt file in your project, add the following line to the file:
```
google-ads-data-manager=0.1.3
```
Optional. Get the utility library and code samples.
1. Download and extract data-manager-python.tar.gz.
2. Navigate to the data-manager-python directory.
3. To install the utility library in your Python environment, run the following command:
```
pip install .
```
4. In your Python project, declare a dependency on the utility library. For example, if using a requirements.txt file in your project, add the following line to the file:
```
google-ads-data-manager-util=0.1.0
```
5. To format and encrypt the data, use the Formatter and Encrypter utilities in your Python project.
6. Browse code samples in the samples subdirectory. Pass the --help argument when running a sample to print a usage statement with expected parameters.
  
  To help you get started with some sample data, use the file at samples/sampledata/audience_members_1.csv.

Node.js

Download and extract ads-datamanager-v1-nodejs.tar.gz.
Navigate to the ads-datamanager-v1-nodejs directory.
Run the following commands to compile and pack the library into a .tgz file for use with npm.
```
npm install
npm pack
```
The commands generate an archive named google-cloud-datamanager-0.1.3.tgz.
In your Node.js project, declare a dependency on the Data Manager API library by adding a dependencies entry for the full path and filename of the google-cloud-datamanager-0.1.3.tgz file.

PHP

Download and extract google-cloud-ads-datamanager-v1-php.tar.gz.
Navigate to the google-cloud-ads-datamanager-v1-php directory.
Run the following command to resolve dependencies for the library:
```
composer update --prefer-dist
```
In the composer.json file of your PHP project on the same host, declare a dependency on the Data Manager API library using the following steps:
1. Add a repositories section that points to the location of the google-cloud-ads-datamanager-v1-php directory.
```
"repositories" : [
   {
      "type" : "path",
      "url" : "PATH_TO_CLIENT_LIBRARY"
   }
]
```
2. Declare a dependency on the Data Manager API library.
```
"require": {
   "googleads/data-manager": "0.1.3"
}
```
(Optional) Get the utility library and code samples.
1. Download and extract data-manager-php.tar.gz.
2. Navigate to the data-manager-php directory.
3. Run the following command to resolve dependencies for the library:
```
composer update --prefer-dist
```
4. In the composer.json file of your PHP project on the same host, declare a dependency on the utility library using the following steps:
  1. Add an entry in the repositories section that points to the location of the data-manager-php directory.
```
"repositories" : [
   {
      "type" : "path",
      "url" : "PATH_TO_UTILITY_LIBRARY"
   }
]
```
  2. Declare a dependency on the utility library.
```
"require": {
   "googleads/data-manager-util": "@dev"
}
```
  To format data, use the Formatter utility in your PHP project.
5. Browse code samples in the samples subdirectory. Run the samples using the following steps:
  1. Navigate to the samples directory.
  2. Set the DATA_MANAGER_PHP_LIB environment variable to the path where you extracted the client library.
```
export DATA_MANAGER_PHP_LIB="PATH_TO_CLIENT_LIBRARY"
```
  3. Run the following command to resolve dependencies for the library:
```
composer update --prefer-dist
```
  4. Run the samples, passing any required arguments. Pass the --help argument when running a sample to print a usage statement with expected parameters.
  To help you get started with some sample data, use the file at samples/sampledata/audience_members_1.csv.

Next steps

Learn more about sending audience data.
Learn more about sending events.
Browse the REST or RPC reference documentation.