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.
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.
The return value for a successful call to addKeyword is your Keyword object with the fields, such as id and status, filled in.
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.
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.
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:
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.
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: