Basic usage

The basic usage of the Java client library is as follows:

Create a new Maven or Gradle project

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

Use the Google Ads API Bill of Materials (BOM) to manage dependency versions.

If you want to run the pre-packaged code examples included in the google-ads-examples module, clone the google-ads-java repository from GitHub or build from source. If you are building from source, ensure that you enable annotation processing in your IDE.

Configure API access

To connect to the Google Ads API, you need to provide authentication and authorization credentials. See the Authentication and authorization guide for details on the required credentials and how to configure the client library.

Make your first call

Once you have configured your credentials, you are ready to make your first API call.

To validate your credentials and make your first call using the cloned google-ads-java repository, 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 hyphens (-).

To run with Gradle:

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

To run with Maven:

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_..._HERE placeholder 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'