AdWords Java Client API

The AdWords API Java client library provides a set of classes that allow you to programmatically access your AdWords account without having to worry about the complexities of interacting with a web service.

See:
          Description

Packages
com.google.api.adwords.lib  
com.google.api.adwords.v10  
com.google.api.adwords.v11  

 

The AdWords API Java client library provides a set of classes that allow you to programmatically access your AdWords account without having to worry about the complexities of interacting with a web service. All the class files are in the package com.google.api.adwords.lib, and they are provided in the jar file adwords-{version}.jar.

This page has the following sections:

Introduction

The AdWords API web services enable programmatic interaction with AdWords accounts, as discussed in the AdWords API Developer's Guide. To use a web service, you write a client application that sends requests to the web service. However, developing web service clients in Java from scratch involves a set of complex steps, such as writing the code to generate the remote classes from the web service definition file (WSDL). Typically, developers use a toolkit such as the Axis toolkit to handle connection to the WSDL, but even with the toolkit you need to do additional work such as precompiling the stub classes. The AdWords API Java Client Library takes away the pain of connecting to the WSDL and precompiling the stubs; it does all that housekeeping kind of work for you. All you have to do is write the code to manage your AdWords accounts.

The classes in the client library are packaged in a jar file that includes all the Axis jars and pre-compiled stub classes needed to write Java clients that programmatically access AdWords accounts. You'll need to extract adwords-{version}.jar from the adwords_api-{version}.zip file, and put adwords-{version}.jar in your Java classpath. That's it; you don't need to put anything else in your classpath or do any pre-compiling. You don't need to worry about accessing the WSDL for the web services; the classes in the client library do it for you.

For more information about using the AdWords API to access and modify AdWords accounts, read the AdWords API Developer Guide at http://www.google.com/apis/adwords/developer/.

What's in the Client Library?

The client library provides full access to all the functionality of the AdWords API web services plus more. It provides:

Installing the Client Library

To install the AdWords API java client Library, extract adwords-{version}.jar from the adwords-{version}.zip file and put it in your Java class path.

The adwords-{version}.jar file appears in the lib directory when adwords-{version}.zip is unzipped.

Note: If you haven't already downloaded the zip file for the Adwords API Java Client Library, you can get it from the Adwords API Developer Website.

 

Writing Programs that Use the Client Library

To write a program that accesses AdWords accounts using the client library, do the following:

  1. Import the following packages or classes:

    com.google.api.adwords.vi.* contains the data classes and service classes. i is the version number of the service you want to use. Packages are versioned so that you can use multiple versions concurently in the same program.
    com.google.api.adwords.lib.AdWordsUser  
    com.google.api.adwords.lib.AdWordsServiceLogger This package is optional, but you need it if you want to log the content of the requests and responses, which can be useful for debugging.
    com.google.api.adwords.ApiException Axis faults get thrown as ApiExceptions. Import ApiException if you want to throw it or catch it.

    For example, a client program that manages campaigns would import the following packages and classes:

  2. import com.google.api.adwords.v5.*;
    import com.google.api.adwords.lib.AdWordsUser;
    import com.google.api.adwords.lib.AdWordsServiceLogger;
    import com.google.api.adwords.ApiException;
    

  3. Create an AdWordsUser instance, specifying the credentials (user, password, tokens and so on) at creation time. For example:
    AdWordsUser myClient = new AdWordsUser(email, password, developerToken, applicationToken, useragent);
    
    See the section Credentials for details of the credentials. You can specify an alternateUrl to target the sandbox instead of the production AdWords service, and a version if you don't want to use the latest version (which is the default).

  4. Instantiate the desired service class by calling the getService method on the AdWordsUser instance with the appropriate service constant, which are defined in BaseCredentials (and are accessible as static from AdWordsUser. For example:
         CampaignService cs = (CampaignService)myClient.getService(me.CAMPAIGN_SERVICE);
    
  5. Create data objects and invoke methods on the service class instance.

    The data objects and methods map directly to the data objects and requests for the corresponding web service, which are described in the Reference Chapter of the AdWords API Developer Guide.

    For example, the following code creates a new campaign:
  6. // Create a new campaign object 
    Campaign newCampaign = new Campaign();
    newCampaign.setDailyBudget(1000000); // Add the new campaign newCampaign = campaignService.addCampaign(newCampaign);
  7. Optionally enable logging to capture the content of the requests and responses. This example sends the information to a file:
    AdWordsServiceLogger.logToFile("myLogFile.txt")

Setting Credentials

To log in to AdWords accounts programmatically, you must supply the following credentials:

Note: In other contexts, a useragent identifies the browser or client application that is sending a request. In the AdWords API, the useragent is slightly different -- it identifies the customer making the request and optionally describes the purpose of the request.

The following credential is optional:

Sample Code

To get started writing your own client, you can use the demo programs in the examples directory. Copy the demo program you want to use and create a file ~/adwords.properties to set your login information. You also need to specify your client token; if you can't remember what it is, go to http://adwords.google.com/; login to your account, click the My Account tab, then click the AdWords API Center tab. Copy and paste your developer token from the resultant page.

Compiling and Running Programs that Use the Client Library

To compile and run a program that uses the AdWords API Java client library, do the following:

  1. Put adwords-{version}.jar in your Java class path.
  2. Compile and run as for any Java program. For example:
javac -classpath adwords-{version}.jar CampaignServiceDemo.java
java -classpath adwords-{version}.jar CampaignServiceDemo

When you run your program, don't worry if you see warnings that attachment support is disabled. This is an Axis thing and shouldn't affect your program.

 



Copyright © 2005 Google Corp. All Rights Reserved.