To discuss and provide feedback on our products, join the official Google Ads Discord channel in the Google Advertising and Measurement Community server.

Getting Started

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

Create a new Maven/Gradle project

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

We recommend using the Google Ads API's Bill of Materials (BOM) to manage dependency versions. This is the best way to avoid dependency conflicts with libraries like Guava and GAX that are also used by other frameworks. The BOM ensures that you use the exact versions of these dependencies that have been tested with the Google Ads client library.

The Maven dependency is:

<!-- Import the Bill of Materials (BOM) to ensure you're using compatible
     versions of all google-ads libraries. -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>google-ads-bom</artifactId>
      <version>40.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<!-- Add the google-ads dependency, without a version. The version is
     managed by the BOM. -->
<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
</dependency>

The Gradle dependency is:

// Import the Bill of Materials (BOM).
implementation platform('com.google.api-ads:google-ads-bom:40.0.0')

// Add the google-ads dependency, without a version.
implementation 'com.google.api-ads:google-ads'

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.

If you are building from source, ensure that you enable annotation processing in your IDE.

Declaring dependencies covered by the BOM

The Google Ads API BOM includes version management for several common libraries, such as Guava, Protobuf, GAX, and gRPC. To avoid potential dependency conflicts, you must not specify a version when declaring dependencies that the BOM covers. The BOM automatically manages the versions for these libraries, ensuring compatibility.

For example, to declare the Guava dependency in Maven, use the following:

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <!-- NO VERSION SPECIFIED -->
</dependency>

And in Gradle:

implementation 'com.google.guava:guava' // NO VERSION SPECIFIED

By omitting the version, you let the BOM manage it, which helps prevent issues caused by incompatible dependency versions. Common indicators of dependency conflicts include NoSuchMethodError or ClassNotFoundException, which can often be resolved by ensuring all BOM-managed dependencies have no version specified.

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'