Introduction
This document describes how to use the Google AdWords API to programmatically access your AdWords accounts through web services.
This document is intended for developers who want to programmatically access AdWords accounts. It assumes that you are familiar with web services and with the programming language you will be using. It also assumes you are familiar with AdWords in general.
Throughout this Developer's Guide, on pages that have major differences between versions, you can choose the documentation for a particular version by clicking links or their differences at the top right corner of the page. Links in the body that take you to a different page take you to the latest version of that page.
Supported version documentation can be accessed via links in the upper right corner of each page. You can view differences between any two versions. There are two rows of version links — in the top row, click the version you want to view, and in the second row click the version to diff against. Text added to the later version is shown with underline and green. Text removed from the later version is shown with strikethrough.
For more information, see Versioning.
Introduction to AdWords API Web Services
Using the AdWords API, you can create and manage campaigns, ad groups, keywords, and ads. You can also generate keyword suggestions, get traffic estimates for predicted impressions, receive clicks and clickthrough rates, and retrieve reports on actual performance.
The core messaging technology for the AdWords API is Simple Object Access Protocol (SOAP), which is an XML and HTTP-based protocol with wide support in the industry. The AdWords API uses document/literal style SOAP 1.1.
To access AdWords accounts programmatically, you build web service clients that use the AdWords API. Typically your web service client program would use a toolkit that knows how to connect to and interact with web services. (See the section About SOAP for more discussion of toolkits.)
The services currently offered are:
- Campaign Service
The Campaign Service lets you create, list, and modify campaigns. For instance, you can change the name, set the daily budget, and define the end date. It also lets you perform actions on a campaign, such as pausing the campaign.
- AdGroup Service
The AdGroup Service lets you create ad groups, list ad groups, associate ad groups with a campaign, and perform actions. For example, you can set the cost-per-click for all keywords in the ad group.
- Criterion Service
The Criterion Service lets you get information about targeting criteria. For example, you can get the keywords for a keyword-targeted campaign or the websites for placement-targeted campaigns. You can create and modify keyword and website targeting criteria.
- Ad Service
The Ad Service lets you create and modify ads, and associate them with an ad group.
- Site Suggestion Service
The Site Suggestion Service lets you estimate the performance of keywords, ad groups, and campaigns.
- Traffic Estimator Service
The Traffic Estimator Service lets you estimate the performance of keywords, ad groups, and campaigns.
You can estimate data, such as the cost-per-click, clickthrough rate, and average position of your ads.
- Keyword Tool Service
The Keyword Tool Service lets you generate keywords based on a seed keyword or on the words found on a web page or web site that you provide.
- Report Service
The Report Service lets you generate reports on the performance of your AdWords campaigns. For
example, you can get reports on the daily number of impressions, clicks, and clickthrough rate.
Advertisers who administer accounts on behalf of other people can get reports about their clients'
AdWords accounts.
- Info Service
The Info Service lets you get basic information about how much you have used the AdWords API.
- Account Service
The Account Service lets you create and modify AdWords accounts.
See the Web Services section for details of the services.
About AdWords
For more information about AdWords accounts, including campaigns, ad groups, keywords, and ads, see the Google AdWords website at http://adwords.google.com/.
Here are quick links to some of the most commonly asked questions:
Signing up to Use the AdWords API Web Services
Before using the AdWords API, you need to sign up at the AdWords API Developer Website. Following the sign-up process, your information will be reviewed and, upon approval, you will be issued two tokens: a Developer Token, which uniquely identifies the developer and tracks your API unit usage, and an Application Token, which uniquely identifies an application that makes requests to the AdWords API.
Both tokens are required to access the AdWords API. They must be included in the header of every request, as discussed in the section Request Header.
Billing for API Usage
Usage of the AdWords API is fee-based. Charges accrue at a rate of US$0.25 (or local currency equivalent) per 1000 API units consumed, where an operation is the smallest unit of work, for example, setting the bid on a single keyword. A single SOAP call can contain many operations. See API operations rate sheet for more details.
Although some advertisers may be eligible for free API units, all developers must provide billing information during the sign-up process. Advertisers will be informed if they are eligible for free API units when their tokens are approved.
Every time you send a request to the AdWords API web services, the header of the request must include your Developer Token, as discussed in the section Request Header, so that your usage can be tracked and billed accordingly. You must also include your Application Token so your application access may be tracked.
You can use InfoService to see your current API usage, for example, to see how many operations you performed during a given date range.
Getting Started Using the AdWords API Web Services
To use the AdWords API, write a client program in a language of your choice (such as Java, Perl, Python, C, C++, PHP). Write your client program to send a request to one of the AdWords Web Services, such as the TrafficEstimatorService or the AdGroupService. The relevant service will process the request and send back a response, which your client program needs to parse.
Since the AdWords API runs as a web service, there is nothing that you need to install related to the AdWords API. The only software you need to install to use the AdWords API is the software for the language and toolkit that you will be using to write your client programs. For example, if you intend to write your client programs in Java, you will need to install Java and also a SOAP toolkit such as Axis. See the section SOAP Toolkits for a list of possible toolkits for various languages.
Namespace - The operations provided by a web service are defined in a WSDL (web services definition language) file which is posted on a website. To connect to a web service, you need to know the URL for the WSDL. Each service (CampaignService, AccountService, etc.) has a different WSDL. The URL for the WSDL has the following form, where <n> is the version number and <Name> is the service name:
https://adwords.google.com/api/adwords/v<n>/<Name>Service?wsdl
For example, the URL for the CampaignService WSDL version 10 is:
https://adwords.google.com/api/adwords/v10/CampaignService?wsdl
Connecting - The exact details of how the client program connects to the WSDL depends on the language and the toolkit being used. Typically, the toolkit has a function for connecting to a service. You simply call the relevant function and pass in the URL for the
WSDL. For example, in Perl you would do the following to connect to the v10 CampaignService:
# Specify the WSDL
$url = https://adwords.google.com/api/adwords/v10/CampaignService?wsdl
# Set up the connection to the service.
my $service = SOAP::Lite->service($url);
XSD Types - Lowercase types shown throughout this document (field, parameter, and return types)
are xsd types in the following namespace:
xmlns:xsd="http://www.w3.org/2001/XMLSchema
Samples and Documentation -
See the code samples in the Sample Code section for examples of how to connect to the AdWords API Web Services in various languages.
After establishing a connection to the WSDL, the client program can send requests to the web service to perform any of the operations supported by the web service. For example, after connecting to the CampaignService, a client program could send an addCampaign request to add a new campaign.
See the AdWords API Web Services section for an overview of how to use each web service.
See the API Reference section for API information about each service.
Developer and Application Tokens
A developer is issued a Developer Token and Application Token when they register to use the AdWords API. Each request to the AdWords API requires a valid Developer Token and Application Token as part of the request header — both are required to gain access to the API.
- Developer Token - Uniquely identifies the developer and is used to track your API unit usage. To safeguard your privacy and protect yourself from fraudulent charges by other users, you should not share your Developer Token with other users. You can find your Developer Token listed on your AdWords API Center, accessible from your My Client Center's "My Account" tab.
- Application Token - Uniquely identifies an application that makes requests to the AdWords API. If your application calls another application, use the Application Token corresponding to the one that actually sends the request. You will need a different Application Token for each application you develop that uses the AdWords API. To request additional tokens, simply click the "add" link in the "Your Application Tokens" section of your AdWords API Center.
For more details about how to use these tokens, see Request Header below.
Logging in to the AdWords API Web Services
You should link your My Client Center (MCC) account to the client account you want to manage. Then, when making an API request, you must include in the request header the email and password of the MCC plus the login email or client customer identification (ID) of the client account.
Note that there are two ways to link your MCC to a client account: "User Interface and API" or "API only". While both give you API access, only one will fully credit the client account's spend towards your API unit usage. For more information, read our FAQ
about My Client Center and API-Only access levels.
For instructions on linking your MCC to client accounts, see How to link an account. For frequently asked questions about MCC, see MCC Help Center.
Note: Security features are designed to prevent unauthorized account access by detecting suspicious login attempts and then blocking access to that account. This happens, for example, if a program attempts to login with an incorrect password too many times. If you attempt to access a blocked account, it will return error code 86, account blocked. To unblock the account, see Error Code 86.
Request Header
All requests sent to the AdWords API web services must include the following header elements:
- email — email address for the AdWords account being accessed.
- password — password for the AdWords account being accessed.
- useragent — an arbitrary string that identifies the customer sending the request.
Note: In other contexts, a useragent header element identifies the browser or client application that is sending a request. In the AdWords API, the useragent element instead identifies the customer making the request and optionally describes the purpose of the request.
- developerToken (or token) — a unique string that identifies you as an authorized developer for the AdWords API. An example developer token string is
ABcdeFGH93KL-NOPQ_STUv. Developer tokens are always 22 characters long. NOTE: We recommend you use developerToken as we plan to remove token in a future release.
- applicationToken — a string that identifies an application as one authorized to call the AdWords API web services. If your application calls another application, use the application token for the one that actually sends the request. An example token string is
ZYXwvu-TSR123_456ABCDE. Application tokens are always 22 characters long.
The following header elements are optional — supply either clientEmail or clientCustomerId, but not both:
- clientEmail — An email address that uniquely identifies a client of an MCC. This header element is only applicable if you have an account with My Client Center (MCC). Provide the clientEmail header element when you want to edit a client's account rather than your own MCC account. If this element is provided, the AdWords API assumes that the account being accessed is the one belonging to the user specified in the clientEmail element. You are still required to pass the <email> and <password> header elements that specify your own email and password for authentication purposes. The client named in <clientEmail> must be managed by the MCC master named in <email>. The purpose of this feature is to let MCC managers manage their customers' accounts without knowing their passwords.
- clientCustomerId — A number, such as 123-456-7890, that uniquely identifies a client of an MCC. You can provide this header element in place of the clientEmail.
The exact details of how the client program specifies a header depends on the language and the toolkit being used, but usually the toolkit has a function for setting a header value. For examples of setting header requests in various toolkits, see the code samples on the AdWords API Developer web site.
For an example of XML code for setting a request header, see the section SOAP Request Example further down this page.
Response Header
All responses returned from the AdWords API web services include the following header elements. We recommend as a "best practice" that you log these values for your own record.
- requestId — unique ID that identifies this request. If you have any support issues, sending us this ID will enable us to find your request more easily
- operations — number of operations in the request
- units — number of API units the request used
- responseTime — elapsed time between the web service receiving the request and sending the response
For an example of XML code for a response header, see the section SOAP Response Example below.
Versioning
The AdWords API supports multiple recent versions of the WSDL to allow developers time to migrate to the most recent version. Once an earlier version of the WSDL has been replaced by an updated version, the older version will be supported for four months after the launch of the newer version.
During this period, the AdWords API will continue to provide developer access to and documentation support for any version dating back two months.
You can tell which version of the WSDL you are accessing based on the access URL namespace, which includes the version number. Versions are named with the letter 'v' followed by whole numbers (v5, v6, etc.).
The Release Notes summarizes changes between versions. In addition, new versions and shutdowns of older version are announced via the AdWords API Blog.
In addition to this documentation, whenever we release a new version of the AdWords API, new versions and older version shutdowns will be announced via the AdWords API Blog.
Deprecation
The term "deprecated" is a warning in the documentation to the developer that an API feature available in a specific version is planned to be removed from a later version — notice that the feature will not normally be removed from the version where it is documented as deprecated, so you can continue using it in that version. The text in the deprecation note should explain which API feature replaces the deprecated one, if any. When you modify your code to support a later version, you should plan accordingly. Deprecated can apply to a service, data object, request or field.
About SOAP
The AdWords API Web Services use document-style versions of the simple object access protocol (SOAP). A client program sends a SOAP request; the web service processes the request and sends a response. Both the request and the response are packaged as XML messages that have a header and a body.
For the AdWords API, all API messages are sent via HTTPS requests. The XML for the SOAP request is 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, as HTTPS) to protect the privacy of your data.
The header describes meta data about the message. In the case of the AdWords API Web Services, the header must include the login email and password and a useragent header identifying the client company. The body of the message specifies the requested operation (such as addAdGroup) along with any applicable parameters (such as the data object for the new ad group).
The requests that a web service can process are defined in a web services definition language (WSDL) file in XML. The WSDL file describes the operations that the web service can perform, the required parameters for each operation, and the response for each operation.
SOAP Toolkits
Typically, to use the AdWords API Web Services, you would download a toolkit that knows 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, as appropriate for the language.
The exact toolkit you would use depends on the language you are using. Some toolkits do more for you or work better than others. To find information on the toolkits we have tested, look at the sample code section:
Sample code - Includes SOAP toolkits for different languages
If you use a SOAP toolkit, you should rarely have to write XML code to use the AdWords API Web Services, since the toolkits handle the XML generation. Some toolkits, however, may require you to hand-code some of the XML yourself. For example, nusoap.php, requires you to write the XML code for input parameters.
Note: The AdWords API uses document/literal style SOAP, not RPC/encoded style. Some toolkits work differently for document-style web services than for RPC-style.
It can sometimes be helpful to capture the XML request and response messages for debugging purposes. See How do I view the XML code generated by the request and response?.
To learn more about SOAP, see the SOAP Tutorial at W3Schools:
http://www.w3schools.com/soap/default.asp
Examples
This section gives examples of WSDL files and XML request messages.
SOAP Request Example
The following code is an example of a SOAP request. The header sets the login email and password along with a useragent string. The body of the message requests a traffic estimate for the keyword flowers at a maximum cost-per-click (maxCPC) of 50000 micros, which in US currency is 5 cents. (Micros are millionths of the fundamental currency unit.)
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns="https://adwords.google.com/api/adwords/v8">
<soap:Header>
<email>loginemail@youraccount.com</email>
<password>secretpassword</password>
<useragent>Your User Agent description</useragent>
<developerToken>_developer_token_here_</developertoken>
<applicationToken>_application_token_here_</applicationtoken>
</soap:Header>
<soap:Body>
<estimateKeywordList>
<keywordRequests>
<type>Broad</type>
<text>flowers</text>
<maxCpc>50000</maxCpc>
</keywordRequests>
</estimateKeywordList>
</soap:Body>
</soap:Envelope>
SOAP Response Example
The following code shows an example of a SOAP response that has the information about the traffic estimates for the previous request.
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<responseTime
soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
soapenv:mustUnderstand="0"
xmlns="https://adwords.google.com/api/adwords/v8">
10636
</responseTime>
<operations
soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
soapenv:mustUnderstand="0"
xmlns="https://adwords.google.com/api/adwords/v8">
1
</operations>
<units
soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
soapenv:mustUnderstand="0"
xmlns="https://adwords.google.com/api/adwords/v8">
1
</units>
<requestId
soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
soapenv:mustUnderstand="0"
xmlns="https://adwords.google.com/api/adwords/v8">
eb21e6667abb131c117b58086f75abbd
</requestId>
</soapenv:Header>
<soapenv:Body>
<estimateKeywordListResponse
xmlns="https://adwords.google.com/api/adwords/v8">
<estimateKeywordListReturn>
<avgPosition>2.9376502</avgPosition>
<cpc>50000</cpc>
<ctr>0.01992803</ctr>
<id>-1</id>
<impressions>62823</impressions>
<notShownPerDay>139255</notShownPerDay>
</estimateKeywordListReturn>
</estimateKeywordListResponse>
</soapenv:Body>
</soapenv:Envelope>
WSDL Example
The requests that a web service can process are described in XML in a web services definition language (WSDL) file. The WSDL file describes the operations that the web service can perform, the required parameters for each operation, and the response for each operation. The complete definition of a single operation can be fairly complex. For example, the definition in the AdGroup Service WSDL for the getName operation, which gets the name of an ad group, given its id, is:
<element name="getName">
<complexType>
<sequence>
<element name="adgroupID" type="xsd:int" />
</sequence>
</complexType>
</element>
<element name="getNameResponse">
<complexType>
<sequence>
<element name="getNameReturn" type="xsd:string" />
</sequence>
</complexType>
</element>
<wsdl:message name="getNameRequest">
<wsdl:part element="impl:getName" name="parameters" />
</wsdl:message>
<wsdl:message name="getNameResponse">
<wsdl:part element="impl:getNameResponse" name="parameters" />
</wsdl:message>
API Reference
