The AdWords API is a collection of web services that you can use to build applications that manage AdWords accounts and their associated campaign data. While the AdWords API is based on SOAP 1.1 Document/literal messaging technology, high-level client libraries are provided to help you more easily and quickly develop applications. To get started, follow the How do I start? steps on the AdWords home page.

1. About This Documentation
2. Web Services Overview
3. Campaign Data Overview
4. Versioning
5. Rate Limiting
6. SOAP+XML Tutorial

About This Documentation

The AdWords API documentation assumes you are familiar with AdWords concepts, SOAP fundamentals, and whichever programming language you will use to interact with the API. If you are new to AdWords, see the AdWords Beginner's Guide. If you are unfamiliar with SOAP, read the W3Schools SOAP tutorial and the Quick SOAP+XML Tutorial below.

Web Services Overview

The AdWords API web services can be grouped by purpose into four categories: Campaign Data Management, Optimization, Account Management, and Utility.

Each of the following web services provides a consistent set of operations: get retrieves entities based on a selector you pass in, and mutate lets you specify a series of operations (add, set, or remove) to perform. Web services that are designed only to provide data do not have a mutate operation, while some web services provide additional special-purpose calls.

Campaign Data Management

Use the campaign data management services to work with AdWords campaigns and their associated entities. Each campaign data management service corresponds to an entity in the campaign data hierarchy (documented in the Campaign Data Overview).

CampaignService

Create, update, and delete campaigns. A campaign organizes one or more ad groups together and has its own budget, bidding strategy, serving date range, and targeting settings.

AdGroupService

Create, update, and delete ad groups. An ad group organizes a set of ads and criteria together, and also provides the default bid for its criteria.

AdGroupAdService

Create, update, and delete ads.

AdParamService

Set ad parameters to quickly updates snippets of parameterized text in your text ads.

CampaignAdExtensionService, AdExtensionOverrideService

Create, update, and delete ad extensions. Campaign ad extensions enrich standard text ads by adding location information, additional links, or a phone number to all ads within a campaign. You can use ad extension overrides to specify a unique location on a per-ad basis.

CampaignCriterionService, AdGroupCriterionService

Create, update, and delete criteria. A criterion describes the conditions that determine whether an ad should appear.

ConversionTrackerService

Measure the effectiveness of your ads and keywords by learning what happens after a user clicks on your ad.

DataService

Retrieve ads campaign management data, based on specified criteria.

FeedService, FeedItemService, FeedMappingService, AdGroupFeedService, CampaignFeedService ^New

Create custom data feeds for use in managing site, phone, and app link extensions.

UserListService

Create, update, and delete user lists. Use user lists and user list criteria to display ads to people who have previously triggered a conversion event on your website.

BudgetService

Create, update, and delete budgets. Use to manage budgets that can be shared across campaigns.

Optimization

Use the optimization services to retrieve performance statistics and discover ideas for new criteria.

ReportDefinitionService

Create and download a variety of performance reports.

TargetingIdeaService

Generate new keyword and placement ideas based on parameters you specify.

TrafficEstimatorService

Get traffic estimates for proposed campaigns, ad groups and keywords.

ExperimentService

Create and run campaign experiments where you can test keywords, bids, and placements.

Account Management

Use the account management services to track your account activity.

AlertService

Retrieve all MCC alerts for a given account.

CustomerService

Retrieve basic details about a client account.

CustomerSyncService

Retrieve a record of campaign data changes within a specified date range.

ManagedCustomerService

Manage client accounts and links between MCC and client accounts.

Utility

Use these utility services as necessary to perform other tasks with the AdWords API.

MutateJobService

Process a large batch of campaign data operations asynchronously. Bulk mutate jobs take longer to complete than synchronous calls to the standard web services, but the processed operations are half the cost.

GeoLocationService

Retrieve coordinates and the canonical address for a specified address.

MediaService

Upload and retrieve IDs for media you use in media-based ads (such as image or video ads).

ConstantDataService

Retrieve constant values used by the API.

LocationCriterionService

Retrieve the ID of a Location criterion.

Campaign Data Overview

Working with campaign data is one of the fundamental tasks you perform with the AdWords API. The table below describes each campaign data entity and its relationship with other campaign data.

Versioning

Version numbering is of the form vYYYYMM and roughly corresponds to the release date. For each release, the release notes contain both an overview of changes and a comprehensive list of API differences.

Rate Limiting

To ensure reliable access to the AdWords API, the system enforces a queries per second (QPS) limit that prevents software from maliciously or unintentionally overloading the servers. If your application exceeds this QPS limit (which varies based on server load and other variables), the server will return an error.

For details on handling this error and more information on rate limiting, see the RateExceededError post on the AdWords API blog.

Quick SOAP+XML Tutorial

This short tutorial shows you how to interact with the AdWords API using cURL. Although cURL and SOAP+XML would be impractical for building a real-world application, it demonstrates how the AdWords API functions at the lowest level.

1. 0. Get your authentication token.

   Use cURL to request your authentication token from ClientLogin:

   curl https://www.google.com/accounts/ClientLogin \
         -d Email=your-google-account-login -d Passwd=your-google-account-password \
         -d accountType=GOOGLE \
         -d source=adwords-tutorial \
         -d service=adwords

   If your login and password are correct, ClientLogin returns your token information. The token after Auth= (shown in bold) is the authentication token you'll use to connect to the AdWords API web services.

   SID=DQAAJIQABADVEOty_EliKKLU1_twfpPAv01q9afKXrn0oMRF_q8UbbiyhwnL_PGOkRQB3LFw2lzcFTH6S_6ddEjEUHT9qbzO5HX-jARdfXaWszzKjOsvxtmSe32Q9ZqT0PaV26kAeoG81RIp1RpJpD2ZpFu1NXrc6T2keiFjEJWXjajVM7DBntGm_zJeoS1QGQbFtrjYCfU
   LSID=DQAAJIcAABC4fL3Wjxwjhwzn-0EYEgE9IoCVj23UVQwH0a0BughMV5hUqGSIGXCTBHx6euvAl1hfduCcZl1HsbKeTQPAzN9vClNAndn4RdPjehbuZCy_UFzr-1KU6-Pmt_E2iPOVF3jneQHVyKf_XDhk_nFT_B8ChI90vqkc3A50IeUzBPPzpinLjTC6cE0leZyFPP4Q0V8
   Auth=DQAAJIYAAAC4fL3Wjxwjhwzn-0EYEgE9IoCZj23UVQwH0a0BughMV5hUqGSIGXCTBHx6euvAl1io1zyeSQeGA_z1D8vOx6TldOrJ7oNLW5PFcVRxhB3SvPd_gVYzFjMUZ2MTJ1KQswlTs6ZtQ4ci11VThUSueOHZTRsthzL5vbLD-DHC8hpBbLm3aP9f3j55_z3RM6i0FcE

2. 1. Create a SOAP request.

   The following XML defines a SOAP request that adds a budget. Save this XML (with your authentication token and account login replacing the placeholders) as hello_world.xml. If you need to identify the clientCustomerId, refer to these instructions.

   <?xml version="1.0" encoding="UTF-8"?>
     <soap:Envelope
       xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns="https://adwords.google.com/api/adwords/cm/v201306">
       <soap:Header>
         <RequestHeader>
           <authToken>YOUR_AUTH_TOKEN</authToken>
           <userAgent>curl-tutorial</userAgent>
           <developerToken>YOUR_ACCOUNT_LOGIN++USD</developerToken>
           <clientCustomerId>XXX-XXX-XXXX</clientCustomerId>
         </RequestHeader>
       </soap:Header>
       <soap:Body>
         <mutate>
           <operations>
             <operator>ADD</operator>
             <operand>
               <name>Hello World! with cURL</name>
               <budget>
                 <period>DAILY</period>
                 <amount>
                   <microAmount>1000000000</microAmount>
                 </amount>
                 <deliveryMethod>STANDARD</deliveryMethod>
               </budget>
               <biddingStrategy
                 xmlns:cm="https://adwords.google.com/api/adwords/cm/v201306"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:type="cm:ManualCPC"/>
               <settings
                 xmlns:cm="https://adwords.google.com/api/adwords/cm/v201306"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:type="cm:KeywordMatchSetting">
                 <cm:optIn>false</cm:optIn>
               </settings>
             </operand>
           </operations>
         </mutate>
       </soap:Body>
     </soap:Envelope>

3. 2. Send the request.

   Use cURL to send this SOAP request to CampaignService:

   curl --header "Content-Type: application/soap+xml" --data @hello_world.xml \
         https://adwords.google.com/api/adwords/cm/v201306/CampaignService

   After the AdWords API server processes your request, it returns a response that contains the XML data representing the newly-added campaign:

     <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
       <soap:Header>
         <ResponseHeader xmlns="https://adwords.google.com/api/adwords/cm/v201306">
           <requestId>dcca9decf95a4a64160524193d9c4059</requestId>
           <operations>1</operations>
           <responseTime>255</responseTime>
         </ResponseHeader>
       </soap:Header>
       <soap:Body>
         <mutateResponse xmlns="https://adwords.google.com/api/adwords/cm/v201306">
           <rval>
             <ListReturnValue.Type>CampaignReturnValue</ListReturnValue.Type>
             <value>
               <id>12345</id>
               <name>Hello World!</name>
               <status>ACTIVE</status>
               <servingStatus>SERVING</servingStatus>
               <startDate>20091031</startDate>
               <endDate>20371231</endDate>
               <budget>
                 <period>DAILY</period>
                 <amount>
                   <ComparableValue.Type>Money</ComparableValue.Type>
                   <microAmount>1000000000</microAmount>
                 </amount>
                 <deliveryMethod>STANDARD</deliveryMethod>
               </budget>
               <biddingStrategy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:type="ManualCPC">
                 <BiddingStrategy.Type>ManualCPC</BiddingStrategy.Type>
               </biddingStrategy>
               <settings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:type="KeywordMatchSetting">
                 <optIn>false</optIn>
               </settings>
               <autoKeywordMatchingStatus>OPT_OUT</autoKeywordMatchingStatus>
               <adServingOptimizationStatus>OPTIMIZE</adServingOptimizationStatus>
               <frequencyCap>
                 <impressions>0</impressions>
               </frequencyCap>
             </value>
           </rval>
         </mutateResponse>
       </soap:Body>
     </soap:Envelope>

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.