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

Getting started

This guide gives a brief overview of how to get started with the client library for Java.

  1. Clone this project in the directory of your choice via:

    git clone https://github.com/googleads/google-ads-java.git
    
  2. Navigate to the google-ads-java directory.

    cd google-ads-java
    

    Now run the following command to install the snapshot version of the library and examples project.

    mvn clean install
    

    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.
  3. 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 the api.adwords prefix in each key from api.adwords to api.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 are authenticating as a manager account, additionally you must specify:

      api.googleads.loginCustomerId --> Manager account ID (with hyphens removed).
      

    If you're accessing the Google Ads API using your own credentials...

    • Follow the instructions on how 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 using System.console. If the example fails, replace the INSERT_CLIENT_ID_HERE and INSERT_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:

      $ cd google-ads-java
      $ mvn clean install
      $ mvn -f google-ads-examples/pom.xml 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 on how 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 using System.console. If the example fails, replace the INSERT_CLIENT_ID_HERE and INSERT_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:

      $ cd google-ads-java
      $ mvn clean install
      $ mvn -f google-ads-examples/pom.xml 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.

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

    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'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"
    
  5. 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"