Google Ads API is returning to beta status. Please read our blog post for more details.

Basic usage

This guide gives a brief overview of design patterns and usage with the client library for Java.

Create a GoogleAdsClient

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:

# Credential for accessing Google's OAuth servers.
# Provided by https://console.developers.google.com.
api.googleads.clientId=INSERT_CLIENT_ID_HERE

# Credential for accessing Google's OAuth servers.
# Provided by https://console.developers.google.com.
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

# Renewable OAuth credential associated with 1 or more Google Ads accounts.
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE

# Token which provides access to the Google Ads API in general. It does not
# grant access to any particular ad account (OAuth is used for this purpose).
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

# Required for manager accounts only: Specify the login customer ID used to
# authenticate API calls. This will be the customer ID of the authenticated
# manager account. You can also specify this later in code if your application
# uses multiple manager account + OAuth pairs.
#
# api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOEMR_ID_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:

File propertiesFile = new File("/path/to/ads.properties");
GoogleAdsClient googleAdsClient =
    GoogleAdsClient.newBuilder()
        .fromPropertiesFile(propertiesFile).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")
        .setLoginCustomerId("INSERT_LOGIN_CUSTOMER_ID_HERE") // Manager accounts only.
        .build();

Get a service client

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...
}

Send feedback about...

Google Ads API Beta
Google Ads API Beta
Need help? Visit our support page.