Getting Started

We recommend using the client library via 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>10.0.0</version>
</dependency>

The Gradle dependency is:

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

You may also build from source. For the purpose of this guide we'll assume 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 UI. For more details see this guide.

OAuth credentials (for access to Google Ads accounts)

OAuth client ID (for access to the Google OAuth API)

Grants access to the OAuth API. Register a client ID/secret in the developer console. One OAuth client ID is generally used for all users/requests (although you may have separate client IDs for different environments/deployments).

Client secret (for access to the Google OAuth API)

Combined with the client ID, grants access to Google's OAuth API.

Google user credential (for access to Google Ads accounts)

Specify a refresh token. If you do not yet have a user credentials, the OAuth section provides details on creating one.

If your access to the Google Ads customer account is via a Google Ads Manager Account, you must also specify:

Login customer ID (for access to Google Ads accounts via 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 via a manager account. There is no need to specify all manager accounts on the path to the customer ID, only the top-most manager ID which you are using for access permissions. For more details, see the related documentation.

OAuth flows

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.

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.

Configure the client library with your credentials

You can either configure the client library with a configuration file or programmatically. For this quickstart guide, we'll use the configuration file approach. This is generally a good approach if you only have one set of credentials (e.g. 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.

$ mvn exec:java -Dexec.mainClass="com.google.ads.googleads.examples.basicoperations.GetCampaigns" \
    -Dexec.args="--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.

$ mvn exec:java -Dexec.mainClass="com.google.ads.googleads.examples.basicoperations.GetCampaigns" \
    -Dexec.args="--help"