This project hosts the Java client library for the Google Ads API.
- Distributed via Maven.
- Easy management of credentials.
- Easy creation of Google Ads API service clients.
- Java 1.7+
- Maven 3.0+
<dependency>
<groupId>com.google.api-ads</groupId>
<artifactId>google-ads</artifactId>
<version>0.1.0</version>
</dependency>
-
Clone this project in the directory of your choice via:
git clone https://github.com/googleads/google-ads-java.git
-
Change into the
google-ads-java
directory.cd google-ads-java
You'll see a parent
pom.xml
for the project, as well as the following subdirectories:google-ads
: source code for the library.google-ads-examples
: multiple examples that demonstrate how to use the library to execute common use cases via the Google Ads API.
-
To run examples, you'll need to compile the
google-ads
andgoogle-ads-examples
code.If you are using an IDE...
- Import the
google-ads-examples
project and confirm that your IDE builds the project successfully.
If you are using Maven from the command line...
-
From the
google-ads-java
directory, install the snapshot version of the library.mvn install
-
Change into the
google-ads-examples
directory.cd google-ads-examples
-
Compile the examples project via:
mvn compile
- Import the
-
Setup your OAuth2 credentials.
The Google Ads API uses OAuth2 as the authentication mechanism. Choose the appropriate option below based on your use case, and read and follow the instructions that the example prints to the console.
If you already have credentials for the AdWords API...
-
You can use the same
ads.properties
file you used for the AdWords API. Simply copy the lines for the following keys and change theapi.adwords
prefix in each key fromapi.adwords
toapi.googleads
:api.adwords.clientId --> api.googleads.clientId api.adwords.clientSecret --> api.googleads.clientSecret api.adwords.refreshToken --> api.googleads.refreshToken api.adwords.developerToken --> api.googleads.developerToken
If you're accessing the Google Ads API using your own credentials...
-
Follow the instructions at https://developers.google.com/google-ads/api/docs/oauth/cloud-project to create an OAuth2 client ID and secret for the installed application OAuth2 flow.
-
Run the AuthenticateInStandaloneApplication example, which will prompt you for your OAuth2 client ID and secret.
If using an IDE:
The example may fail with an
IllegalArgumentException
if your IDE does not support usingSystem.console
. If the example fails, replace theINSERT_CLIENT_ID_HERE
andINSERT_CLIENT_SECRET_HERE
values in the AuthenticateInStandaloneApplication example with the client ID and secret from the step above, then run the example again.If using the command line:
$ mvn exec:java -Dexec.mainClass="com.google.ads.googleads.examples.authentication.AuthenticateInStandaloneApplication"
-
Copy the output from the last step of the example into a file named
ads.properties
in your home directory.
If you're accessing the Google Ads API on behalf of clients...
-
Follow the instructions at https://developers.google.com/google-ads/api/docs/oauth/cloud-project to create an OAuth2 client ID and secret for the web application OAuth2 flow.
-
Run the AuthenticateInWebApplication example, which will prompt you for your OAuth2 client ID and secret.
If using an IDE:
The example may fail with an
IllegalArgumentException
if your IDE does not support usingSystem.console
. If the example fails, replace theINSERT_CLIENT_ID_HERE
andINSERT_CLIENT_SECRET_HERE
values in the AuthenticateInWebApplication example with the client ID and secret from the step above, then run the example again.If using the command line:
$ mvn exec:java -Dexec.mainClass="com.google.ads.googleads.examples.authentication.AuthenticateInWebApplication"
-
Copy the output from the last step of the example into a file named
ads.properties
in your home directory.
-
-
After following the instructions printed to the console, you should have a file named
ads.properties
in your home directory.To ensure that the credentials in that file are valid, run the GetCampaigns example, either via your IDE or from the command line using Maven. This example requires a
--customerId
parameter where the value is your Google Ads account's customer ID without dashes. Here's how you can pass that information if you are using Maven from the command line.$ 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 theINSERT_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"
To issue requests via the Google Ads API, you first need to create a GoogleAdsClient. For convenience, you can store the required settings in a properties file with the following format:
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
This configuration file format is similar to the format used in the AdWords
API's
client library for Java, but
uses property keys with the prefix api.googleads
instead of api.adwords
so you can have separate configuration settings for the AdWords API and the
Google Ads API.
If you have an ads.properties
configuration file in the above format in your
home directory, you can use the no-arg version of fromPropertiesFile
as
follows:
GoogleAdsClient googleAdsClient =
GoogleAdsClient.newBuilder()
.fromPropertiesFile().build();
If your configuration file is not in your home directory, you can pass the
file location to the fromPropertiesFile
method as follows:
GoogleAdsClient googleAdsClient =
GoogleAdsClient.newBuilder()
.fromPropertiesFile("/path/to/ads.properties").build();
You can also construct a Credentials
object by specifying the client ID,
client secret, and refresh token at runtime, then pass that to the
GoogleAdsClient
builder as follows:
Credentials credentials =
UserCredentials.newBuilder()
.setClientId("INSERT_CLIENT_ID")
.setClientSecret("INSERT_CLIENT_SECRET")
.setRefreshToken("INSERT_REFRESH_TOKEN")
.build();
GoogleAdsClient googleAdsClient =
GoogleAdsClient.newBuilder()
.setCredentials(credentials)
.setDeveloperToken("INSERT_DEVELOPER_TOKEN_HERE")
.build();
Once you have an instance of GoogleAdsClient
, you can obtain a service client
for a particular service using one of the get...ServiceClient()
methods.
Wrapping this call in a try with resources block ensures that any
resources required to make the Google Ads API request are released upon exit
from the try
block.
try (CampaignServiceClient reportingServiceClient = googleAdsClient.getCampaignServiceClient()) {
// Send a request...
}