Section 13.2. Working with the AdWords API Web Service

13.2. Working with the AdWords API Web Service

To program with the AdWords API, you need to have a basic understanding of how to work with a web service.

Web services are programs that are used to glue together disparate parts of applications across the far-flung Web. They often join together programs running on several servers, with each of the programs supplying a part of the larger software application. Web services constitute a safe and recognizable way to connect the parts of these programs so that they can be used by a wider population.

A web service exposes functions (also called web methods ) over the Internet. These web methods are a kind of gating mechanismthey have to be called with the specified arguments, in some cases in a given order. Further, web services are designed to prevent an external programmer from harming the remote server via the methods the server exposes.

For example, an online comparison pricing service, such as CNET or BizRate, might make information about its data available via a web service and web methods. A hypothetical web method, getPrices, might return prices for an item when passed the item's product code. An external program could use this web method to display competitive pricing information to end users.

Of course, to use the web methods associated with a web service, you need to know that the service and methods exist. More specifically, in order to code a call to a web method and web service, you need to know an address for the web service, what the methods associated with the service are called, what kinds of values they take, and what kinds of values they return. In other words, to use the pricing web method example, you need to know that the method is called getPrices, that it takes a UPC product code, and returns an array of merchant IDs and prices.

As a programmer, how are you going to know this information so you can use the web service? Thankfully, there is a standard way to discover the crucial information about web methods and web services.

13.2.1. The AdWords API WSDL Files

Each web service provides a "contract" consisting of a WSDL (Web Services Description Language) file that provides information about the service and its methods. WSDL files describe a web service and its methods. If you have, or can find, a WSDL file, you know how to invoke the methods exposed by a web service, and you also know what types of values each web method will return. Using the WSDL file, some modern programming environments, such as Visual Studio.NET, automatically generate most of the code you need to use the web service and its methods.

Technically, a WSDL file is a text file written in XML following a schema specified for WSDL files by the W3C organization (see http://www.w3.org/2002/ws/desc/ for more information about the W3C WSDL specification). The XML elements in the WSDL file correspond to programmatic methods that can be used to set values, call functions, and evaluate return values and error codes in a web service.

The AdWords API provides a separate WSDL file for each of the eight AdWords API services , which correspond to the organization of an AdWord account. You'll find a description of each of these services in "The AdWords API Services" later in this chapter, along with the address you'll need to access the corresponding WSDL file.

To get a taste of how the discovery and programming process works with one of the AdWord services and the related WSDL file, suppose you want to use Keyword Service to add a new keyword to an Ad Group. The method that adds a keyword is defined in the XML WSDL file for the Keyword web service like this:

 <wsdl:operation name="addKeyword">   <wsdlsoap:operation soapAction="" />   <wsdl:input name="addKeywordRequest">      <wsdlsoap:header message="impl:email" part="email" use="literal" />      <wsdlsoap:header message="impl:clientEmail" part="clientEmail" use="literal"      />      <wsdlsoap:header message="impl:password" part="password" use="literal" />      <wsdlsoap:header message="impl:useragent" part="useragent" use="literal" />      <wsdlsoap:header message="impl:token" part="token" use="literal" />      <wsdlsoap:body namespace="https://adwords.google.com/api/adwords/v2"         use="literal" />   </wsdl:input> <wsdl:output name="addKeywordResponse">   <wsdlsoap:header message="impl:responseTime" part="responseTime" use="literal" />   <wsdlsoap:header message="impl:operations" part="operations" use="literal" />   <wsdlsoap:body namespace="https://adwords.google.com/api/adwords/v2"       use="literal" /> </wsdl:output>

If you were to make use of this WSDL method definition in a program, you would need to know the meaning of the arguments you need to pass to the method. These are the request headers , which must be sent to all AdWords API method requests and are shown in Table 13-1.

Table 13-1. AdWords API web services request headers

Argument	Meaning
clientEmail	This is an optional field used when you are managing multiple AdWords accounts through a My Client Center account. If you supply a client email, you still must supply your own email and password, and you can only manage the account referenced by the client email.
email	Email for the AdWords account being accessed.
password	Password for the AdWords account being accessed.
token	Your AdWords API developer token.
useragent	You can put anything you want in the useragent field. It's good form to use this field to identify the purpose of your request.

See Chapters 14 and 15 for examples using the AdWords API web services request headers.

Besides the request headers, which must be used for all calls to the AdWords services, the addKeyword method needs to be passed the keyword information as a Keyword type. Here's the XML definition of the Keyword complex type in the Keyword Services WSDL file:

 <complexType name="Keyword">    <sequence>    <element name="type" nillable="true" type="impl:KeywordType" />    <element name="maxCpc" type="xsd:long" />    <element name="adGroupId" type="xsd:int" />    <element name="language" nillable="true" type="xsd:string" />    <element name="status" nillable="true" minOccurs="0"       type="impl:KeywordStatus" />    <element name="negative" type="xsd:boolean" />    <element name="destinationUrl" nillable="true" type="xsd:string" />    <element name="text" nillable="true" type="xsd:string" />    <element name="id" type="xsd:long" />    <element name="exemptionRequest" nillable="true" type="xsd:string" />    </sequence> </complexType>

Table 13-2 shows the meaning of the elements passed as part of a Keyword object and returned by the KeywordService API.

Table 13-2. Elements of a Keyword

Element	Type	Meaning	Comment
adGroupID	Integer	AdGroup associated with the keyword.	Required.
destinationURL	String	Destination URL for the keyword.	Optional. If omitted, the destination URL for the ad is used.
exemptionRequest	String	Reason for allowing a text ad or creative that violates Google editorial policy.	Optional. Specifying exemptionRequest makes sure that your API call will not throw an exception, but does not guarantee that the related ad will run.
id	Long integer	The numeric ID associated with the keyword.	Provided when the keyword is created.
language	String	Language for the keyword.	Optional.
maxCpc	Long integer	Maximum CPC for the keyword.	Optional. If 0 is given as the value for maxCPC, then the maximum CPC for the related AdGroup is used.
negative	Boolean	A true value means that this keyword is used for a negative match.	Optional.
status	KeywordStatus enumeration	Corresponds to the status assigned by AdWords for keywords.	Returned by system; possible values for this enumeration are: Normal, InTrial, OnHold, Disabled, Disapproved, Deleted.
text	String	The text of the keyword.	Required. 80 characters maximum.
type	KeywordType enumeration	Kind of targeting.	Required. Possible values for this enumeration are: Broad, Phrase, Exact.

The return value for a successful call to addKeyword is your Keyword object with the fields, such as id and status, filled in.

13.2.2. SOAP

Web services, specified by a WSDL file, can be published using a SOAP (Simple Object Access Protocol) mechanism running over HTTP (or some other transport protocol) or using HTTP Get requests.

Some web services are designed to use SOAP over HTTP but also can run as an HTTP request. The advantage of using HTTP requests is that it is simple to test web services (you just issue a request as a URL). However, using SOAP to encapsulate web service requests from the underlying transport mechanism (such as HTTP or HTTPS) is probably a more robust and secure architecture.

The Google AdWords API web services are implemented using SOAP over HTTPS. Requests are sent as an HTTP POST request with a special SOAPAction header; the response is sent back as the response to the POST.

All AdWords API calls are encrypted with SSL (that is, via HTTPS) for increased security.

The SOAP standard (see http://www.w3.org/TR/SOAP/ for details) defines three parts used for communication between web service publishers, such as Google AdWords, and programs that use the methods exposed by the web service:

• An envelope that defines a framework for describing what is in a message

• Encoding and decoding rules for types of data used in the message

• A way of expressing remote calls to methods (also called remote procedure calls, or RPC) and the method response

As a general matter, to use the AdWords API web servicesor any other web serviceyou don't need to know much about SOAP encoding or the specific XML specified by the WSDL file.

Depending on the programming language and development environment you are using, many of these lower-level details are taken care of by tools built into your development environment or by a toolkit you can download. These tools know how to interpret WSDL files and how to encode and decode XML request and response messages. When an AdWords API web service receives a request, it sends back the response as an XML message. The web service toolkits know how to parse the response and return a data structure or object back to the caller that can easily be used in your programming environment.

Table 13-3 shows the most commonly used SOAP toolkits.

Table 13-3. Common SOAP toolkits

Language	Toolkit	Where to get
Java	Apache Axis	http://ws.apache.org/axis/
.NET (C#, VB, etc.)	n/a	Built into Visual Studio .NET
Perl	SOAP::Lite	http://www.soaplite.com/
PHP	Pear NuSOAP	http://pear.php.net/ http://cvs.sourceforge.net/viewcvs.py/nusoap/lib/nusoap.php
Python	SOAPPy	http://pywebsvcs.sourceforge.net/

13.2.3. Choosing a Programming Language

You can create programs that interact with the AdWords API in any language that can use a SOAP-based web service, which is most languages. So the choice of language and development environment should largely depend on the standards of your organization and what your organization's programmers are familiar with.

That said, the following languages are a particularly good place to start creating AdWords API applications, because Google provides sample code in these languages and they also have easily available tools for working with SOAP:

• C# .NET

• Java

• Perl

• PHP