AdWords API services
The AdWords API 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. Services that are designed only to provide data do not have a
mutate operation, while some 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.
- CampaignService
- Create, update, and remove 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 remove 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 remove ads.
- CampaignExtensionSettingService
- Create, update, and remove 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.
- CampaignCriterionService, AdGroupCriterionService
- Create, update, and remove criteria. A criterion describes the conditions that determine whether an ad should appear.
- ConversionTrackerService, OfflineConversionFeedService
- Measure the effectiveness of your ads and keywords by learning what happens after a user clicks on your ad. OfflineConversionFeedService handles offline conversions importing.
- DataService
- Retrieve ads campaign management data, based on specified criteria.
- FeedService, FeedItemService, FeedMappingService, AdGroupFeedService, CampaignFeedService
- Create custom data feeds for use in managing site, phone, and app link extensions.
- AdwordsUserListService
- Create, update, and remove user lists. Employ 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 remove 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.
- 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 manager 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. Batch processing 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
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.
|
Entity
Child Entities (quantity)
|
Data Type | Description |
|---|---|---|
|
Campaign
Ad groups (1+)
Campaign target lists (7)
Campaign ad extensions (0+)
Campaign criteria (0+)
|
Campaign
|
A campaign organizes one or more ad groups together and has its own budget, bidding strategy, and serving date range. |
|
Ad Group
Ads (1+)
Criteria (1+)
|
AdGroup
|
An ad group organizes a set of ads and criteria together, and also provides the default bid for its criteria. |
|
Ad
Ad extension overrides (0+)
|
AdGroupAd
|
Available ad types are documented in the API reference as subclasses of the abstract Ad type. |
|
Criterion
None
|
AdGroupCriterion,
CampaignCriterion |
A criterion describes the conditions that determine if an ad should (biddable criterion) or should not (negative criterion) appear. An ad group criterion affects ads in the parent ad group. A campaign criterion, which is always a negative criterion, defines conditions that prevent the campaign's ads from showing. |
|
Ad Extension
None
|
CampaignExtensionSetting
|
Campaign ad extensions enrich standard text ads by adding location information, additional links, or a phone number to all ads within a campaign. |
|
Feed
None
|
Feed
|
Feeds act as conduits for data to ad extensions (sitelink, phone, app). |
|
User List
None
|
UserList
|
User lists keep track of which users have previously expressed interest in your website. You can target ads to this set of users by creating a user list criterion and linking it to an existing user list. |
|
Budget
None
|
Budget
|
Budgets are used for managing the amount of money spent on campaigns. A Budget can be shared across different campaigns and the system will determine the optimal allocation. |
Use cases
We list some typical use cases for making use of the AdWords API.
Campaign management
The AdWords API aims to expose most of the functionality available in the AdWords web interface, including the ability to add, edit, and remove campaigns, ad groups, ads, keywords, etc. Display network features are also supported, including placements, product ads, and remarketing. This functionality is commonly used:
- To provide custom interfaces to manage campaigns, and integrate with analytics and CRM systems.
- To leverage internal data feeds to create new ads or pause and unpause campaigns based on business criteria.
- In scripts that automate manual and time intensive tasks.
See: CampaignService, CampaignCriterionService, AdGroupService, AdGroupAdService, AdGroupCriterionService
Ads management based on inventory
While studying conversion numbers for their campaigns, some customers discover that a significant amount of their ad clicks take visitors to a page for an item that is out of stock. One way to avoid this is to automatically manage your ads via the API based on your available stock. Every time an item availability is updated, a corresponding ad or ad group could be paused or unpaused, saving the budget and potentially improving conversion rates.
See: AdGroupService, AdGroupAdService
Bid management
Using the reporting features of the API, keyword statistics can be retrieved, including fields related to impressions, clicks, conversions, etc. Other services provide information about how a keyword might have performed recently with different bids or with forward-looking estimates for a proposed bid change. Once you’ve done the calculations, you can apply the bid changes to your keywords and start the process again.
See: AdGroupCriterionService, DataService, TrafficEstimatorService, Bidding, Reporting Basics
Dynamic ad text
Because ad text is frozen when the ad is created, updating an ad with the most recent price or quantity information requires constantly recreating it and waiting for it to be reapproved. The API provides a feature called ad customizers that allows for dynamic sections of an ad to be defined, which are then replaced by custom values when the ad serves. These values can be updated using the API throughout the day and usually without reapproval, allowing for ads with the freshest available content.
See: Ad Customizers
Bulk upload
The API provides functionality to simplify the deployment of large new campaigns, which can be difficult for customers going after long tail keywords. Our bulk job service allows you to upload large numbers of ads and keywords asynchronously, freeing up your application to do other work. Operations are applied automatically, removing the need to throttle requests to stay under the system's rate limits.
See: Batch Processing
Keyword research for campaign management
Long tail advertisers looking to expand the keyword base they are bidding on can take advantage of the keyword research functionality provided by the API. New keyword ideas can be generated from a sample keyword or website. These keywords are returned along with the search volumes they received over the last year. You can then estimate the clicks they would receive within your ad group, as well as the total cost you can expect them to generate. The API allows you to programmatically leverage much of the functionality provided by the Keyword Tool and Traffic Estimator in the AdWords web interface.
Note that keyword research for any purpose other than active AdWords campaign management is not permitted.
See: Generating Targeting Ideas, Estimating Traffic
Performance dashboard
The reporting features of the API allow for reports to be defined on-demand, and the data is usually available within seconds. You can use this to create custom dashboards for monitoring the performance of accounts, including fine-grained details such as per-keyword statistics. Powerful segmentation and filtering options allow you to focus in on the exact data that your users care about without extra client-side logic.
If you are an agency and you plan to create a performance dashboard accessible by your clients, make sure the result will display the appropriate Required Minimum Functionality.
See: Reporting Basics
Synchronization with internal systems
In many cases, it's useful to integrate information from AdWords with other internal systems, such as billing or conversion tracking. In particular, you may want offline access to data such as campaign and ad group listings or performance statistics such as impressions, clicks, cost, CTR, etc. The data can initially be extracted via reports and synchronized regularly by pulling updates for added campaigns. The AdWords API allows you to identify objects created or changed during particular date ranges and retrieve them independently.
