Documentation for the requested version is not available.Documentation for the requested diff is not available.
The AdWords API Developer's Guide describes how to use the Google AdWords API to manage your AdWords accounts.
This guide 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 Google AdWords in general.
Documentation for each supported version of AdWords API is embedded into this single guide. To view documentation for a specific version of the API, select it from the drop-down list in the top-right corner. You can also use this drop-down menu to view differences between two versions. When viewing differences, added text will display underlined and green and removed text will display with strikethrough.
Note: This guide uses a cookie to persist the version selection between pages. If you have cookies disabled, pages within this guide will always display the latest version upon loading.
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.
To access and manage your AdWords account using the AdWords API, you build a client application that connects to one or more of the provided web services. While each service can be used independently, most real-world scenarios (such as adding a new campaign that has ad groups, ads, and keywords) require a client application to use multiple services.
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.
The AdWords API is composed of the following web services:
|
CampaignService
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.
AdGroupService
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.
CriterionService
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.
AdService
The Ad Service lets you create and modify ads, and associate them with an ad group.
SiteSuggestionService
The Site Suggestion Service lets you estimate the performance of keywords, ad groups, and campaigns.
TrafficEstimatorService
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.
KeywordToolService
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.
ReportService
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.
InfoService
The Info Service lets you get basic information about how much you have used the AdWords API.
AccountService
The Account Service lets you create and modify AdWords accounts.
For more information on each web service, see the Web Services Overview.
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 some quick links to more information:
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.
Calls to AdWords API web services are charged to your account in the form of API units. 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 Usage & Fees 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.
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 TrafficEstimatorService or AdGroupService. The relevant service will process the request and send back a response, which your client program needs to parse.
Since the AdWords API is a set of web services, 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.
The operations provided by a web service are defined in a WSDL file. Before connecting to a web service, you need to know the URL that points to its WSDL file. Each AdWords API web service has its own WSDL. The URL for each WSDL has the following form, where N is the version number and SERVICE_NAME is the service name:
https://adwords.google.com/api/adwords/vN/SERVICE_NAME?wsdl
For example, this is the URL for the v12 CampaignService WSDL:
https://adwords.google.com/api/adwords/v12/CampaignService?wsdl
The details of how your client application connects to the WSDL depends on the programming language and SOAP toolkit being used. SOAP toolkits typically provide a function for connecting to a service at a specified URL. For example, the following Perl code connects to the v12 CampaignService:
# Specify the WSDL $url = https://adwords.google.com/api/adwords/v12/CampaignService?wsdl # Connect to the service using the SOAP::Lite toolkit my $service = SOAP::Lite->service($url);
After establishing a connection to the web service, your client application use the web service to perform any of the operations supported by the web service. For example, after connecting to CampaignService, a client program could send an addCampaign request to add a new campaign.
Uppercase types, such as Campaign and NetworkType, shown throughout this guide's API Reference are complex data structures or enumerations defined in the WSDL.
Lowercase types, such as boolean and string, shown throughout this guide are XML Schema datatypes in the following namespace:
http://www.w3.org/2001/XMLSchema
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 access the API.
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.
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 information on how to include these tokens with your requests, see Request Header below.
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.
The following header elements are required for requests sent to the AdWords API web services:
Email address for the AdWords account being accessed.
Password for the AdWords account being accessed.
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.
A string that uniquely identifies an AdWords API developer. An example developer token string is ABcdeFGH93KL-NOPQ_STUv. Developer tokens are 22 characters long.
A string that uniquely identifies an application that's authorized to access the AdWords API web services. Always use the applicationToken corresponding to the application that directly calls AdWords API. An example token string is ZYXwvu-TSR123_456ABCDE. Application tokens are 22 characters long.
The following header elements are optional. You can set either clientEmail or clientCustomerId, but not both:
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. The client named in clientEmail must be managed by the MCC master named in email. The purpose of this header element is to let MCC managers manage their customers' accounts without knowing their passwords.
Note: You are still required to pass the <email/> and <password/> header elements that specify your own email and password for authentication purposes.
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.
For an example of XML code for setting a request header, see the section SOAP Request Example further down this page.
All responses returned from the AdWords API web services include the following header elements. As a best practice, we recommend that you log these values.
Uniquely identifies this request. If you have any support issues, sending us this ID will enable us to find your request more easily.
Number of operations in the request.
Number of API units the request used.
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.
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 its URL, which includes the version number. Version names are of the form vN.
The Release Notes summarizes changes between versions. In addition, new versions and shutdowns of older version are announced via the AdWords API Blog.
The term "deprecated" is a warning to the developer that an API feature will probably 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.
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. The header contains metadata about the message, and the body specifies the requested operation.
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 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.
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 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.
The SOAP toolkit you use depends on the programming language your client is written in. For information on the toolkits we have tested, see SOAP Toolkits.
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.
This section provides examples of WSDL files and XML request messages.
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>
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>
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>