Getting Started

We recommend using the client library with Apache Maven (or Gradle).

Create a new Maven/Gradle project

Create a new Maven/Gradle project in the IDE of you choice. Our artifacts are published to the Maven central repository.

The Maven dependency is:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>34.0.0</version>
</dependency>

The Gradle dependency is:

implementation 'com.google.api-ads:google-ads:34.0.0'

You can also build from source. For the purpose of this guide, it's assumed that you have a project setup with the required dependencies available.

Obtain credentials to authenticate with the API

Access to the Google Ads API requires OAuth credentials and a Google Ads API developer token. This section explains what these are, how they're used, and how they're obtained.

Developer token (for access to the API)

The developer token is linked to a manager account and can be found in the Google Ads web interface.

Although the developer token is linked to a manager account, it doesn't provide access to that account. Instead, the developer token grants access to the API in general, and account level access is configured through OAuth.

OAuth credentials (for access to Google Ads accounts)

To authorize as Google account users with access to Google Ads accounts, you must provide a set of OAuth credentials.

There are two OAuth flows that are generally used: desktop (installed) app or web app. The main difference between the two is that desktop apps must open the system browser and supply a local redirect URI to handle responses from Google's authorization server, whereas web apps can redirect an arbitrary third-party browser to complete authorization and send the credentials back to your server. The library also supports the less commonly used service account flow.

If you authorize using your own credentials (desktop app flow)

Refer to the OAuth desktop app flow. This includes all the details you need for authorizing with your own credentials.

If you authorize as a third-party Google user (web flow)

Refer to the OAuth web app flow. This gives an example of how to set up OAuth authorization for arbitrary third-party users.

If you authorize as a Google Apps Domain user (service account flow)

Refer to the OAuth service account flow. This gives an example of how to set up OAuth authorization for Google Apps Domain users.

If your access to the Google Ads customer account is through a Google Ads manager account, you must also specify a login customer ID as described below.

Login customer ID (for access to Google Ads accounts through a manager account)

Optionally, specify the customer ID of a manager account which gives access to the serving account. This must be specified if your access to the customer account is through a manager account. There is no need to specify all manager accounts on the path to the customer ID, only the topmost manager ID which you are using for access permissions. For more details, see the related documentation.

Configure the client library with your credentials

You can either configure the client library with a configuration file, environment variables, or programmatically. For this guide, we'll use the configuration file approach and focus on the desktop and web flows. Using a configuration file is generally a good approach if you only have one set of credentials (for example, you manage accounts under a single manager).

Create a file ~/ads.properties with the following content:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

Replace the placeholders with your credentials obtained in the previous step.

Additionally, if your refresh token is for a manager account, you should specify the customer ID of this account as the login customer:

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Validate the credentials

To ensure that everything is setup correctly, we'll run the GetCampaigns example.

First, navigate into the google-ads-examples directory.

$ cd google-ads-examples

This example requires a --customerId parameter where the value is your Google Ads account customer ID without dashes.

To run with Gradle:

$ ./gradlew -q runExample --example="basicoperations.GetCampaigns --customerId INSERT_CUSTOMER_ID_HERE"

Explore other examples

The examples package in google-ads-examples contains several useful examples. Most of the examples require parameters. You can either pass the parameters as arguments (recommended) or edit the INSERT_XXXXX_HERE values in the source code. To see a usage statement for an example, pass --help as the only argument.

With Gradle:

$ ./gradlew -q runExample --example="basicoperations.GetCampaigns --help"

You can also use the listExamples task in Gradle to list all examples, examples in a subdirectory, or examples where the description includes a search term.

# List all examples:
$ ./gradlew -q listExamples
# List examples in the 'basicoperations' subdirectory:
$ ./gradlew -q listExamples --subdirectory='basicoperations'
# Search for examples where the description includes 'Performance Max':
$ ./gradlew -q listExamples --searchTerm='Performance Max'