Enterprise Web Services

Services Overview

The Search Marketing API services overview include:

Setting Tactics

Search tactics include: Sponsored Search and Content Match®.

Sponsored Search displays your ads to users who enter search queries related to your keywords. Sponsored Search has two match types:

Standard - Displays ads for exact matches to your keywords, as well as for singular or plural variations, common misspellings, and topics that are relevant to your keywords, titles, and descriptions.

Advanced - Displays ads for a broader range of searches relevant to your keywords, titles, descriptions, and web content.

Content Match® displays your ads on web pages with articles, reviews, news or other relevant content.

Elements

Use the sponsoredSearchON, advancedMatchON, and contentMatchON elements to enable or disable tactics:

To enable Sponsored Search with the standard match type, set the sponsoredSearchON element to true at all levels.
To enable Sponsored Search with the advanced match type, set both the sponsoredSearchON and the advancedMatchON elements to true at all levels.
To enable Content Match, set the contentMatchON element to true at all levels.

The sponsoredSearchON, advancedMatchON, and contentMatchON elements are all optional. If you do not specifically enable, disable, or set these elements to null, they are all enabled by default.

Note: SponsoredSearchON element and the contentMatchON element cannot both set disabled at the same time. Either the sponsoredSearchON element or the contentMatchON element must be enabled.

And, if the sponsoredSearchON element is enabled, you must provide a value for the sponsoredSearchMaxBid element at either the ad group or keyword level. If the contentMatchON element is enabled, you must provide a value for the contentMatchMaxBid element at the ad group level.

For keywords, if you want the keyword to be served with the standard match type, the sponsoredSearchON element must be enabled at the account, campaign, and ad group levels. If you want the keyword to be served with the advanced match type, the advancedMatchON element must be enabled at the account, campaign, ad group, and keyword levels and the sponsoredSearchON element must be enabled at the account, campaign, and ad group levels. If you want the keyword to be served with Content Match, the ContentMatchON element must be enabled at the account, campaign, and ad group levels.

To summarize:

The sponsoredSearchON, advancedMatchON, and contentMatchON elements are all optional and are all enabled, set to true by default.
The sponsoredSearchON element and the contentMatchON element cannot both be disabled, set to false at the same time.
If the sponsoredSearchON element is enabled, set to true, you must provide a value for the sponsoredSearchMaxBid element.
If the contentMatchON element is enabled, set to true, then you must provide a value for the contentMatchMaxbid element.
An element must be enabled, set to true at all higher levels for it to take effect at a lower level. If an element is disabled at any higher level, it is effectively disabled at all lower levels.

Element	Account	Campaign	Ad Group	Keyword
sponsoredSearchON	true/false	true/false	true/false	n/a
advancedMatchON	true/false	true/false	true/false	true/false
contentMatchON	true/false	true/false	true/false	n/a
sponsoredSearchMaxBid	n/a	n/a	Required if sponsoredSearchON is enabled.	optional
contentMatchMaxBid	n/a	n/a	Required if contentMatchON is enabled.	n/a

Examples

The following examples show how different tactic settings affect campaigns, ad groups, and keywords.

Example 1:

The advanced match type is enabled at the keyword level, but it will have no effect because the advanced match type is disabled at the ad group level.
Content Match is enabled at the ad group level, but it will have no effect because Content Match is disabled at the campaign level.

In this example, the keyword will be served with the standard match type because Sponsored Search is enabled at the account, campaign, and ad group levels.

Tactic (element)	Account	Campaign	Ad Group	Keyword
SponsoredSearchON	true	true	true	n/a
AdvancedMatchON	true	true	false	true
ContentMatchON	true	false	true	n/a

Example 2:

The advanced match type is enabled at the keyword level, but it will have no effect because the advanced match type is disabled at the ad group level.
Sponsored Search is enabled at the ad group level, but it will have no effect because Sponsored Search is disabled at the campaign level.

In this example, the keyword will not be served because Sponsored Search is disabled at the ad group level.

Tactic (element)	Account	Campaign	Ad Group	Keyword
SponsoredSearchON	true	false	true	n/a
AdvancedMatchON	true	true	false	true
ContentMatchON	true	true	true	n/a

Setting Bids

Bids represent the amount you are willing to pay for a click, although you may actually be charged less for a click depending on the competition in your campaign’s marketplace and the quality of your ad. The bid that is actually used will depend on the search tactic that causes the ad to be served, either Sponsored Search or Content Match®. See Setting Tactics.

Bids and Bid Limits

You set bids when you create ad groups and keywords. See the AdGroupService Overview and the KeywordService Overview.

You set bid limits when you enable campaign optimization and set up the optimization guidelines. See the CampaignService Overview.

In both cases, you should specify the bid using the correct decimal precision for the market currency. Currently, all market currencies require 2 decimal point precision, except Japan (JP) and Korea (KR) which require 0 decimal point precision.

EWS supports two systems for setting bids and bid limits:

Variable Minimum Bids, and
Market Minimum Bids.

Both systems are described below. Please note that the values for the base bids are not the same for each system; and, the values for the minimum bids are not the same for each system.

Variable Minimum Bids

The terms for Variable Minimum Bids include:

Max bid – maximum bid set by you, the user (EWS optional value).
Min bid – minimum bid set by the system (EWS read-only value).
Base bid – base bid established for your market (not available through EWS).

You cannot enter the marketplace with a max bid that is below the base bid; if the max bid is below the base bid, a SOAP fault is thrown. You can enter the marketplace with a max bid that is above or below the min bid; however, if the max bid is below the min bid, a warning is thrown. In either case, if a SOAP fault or warning is thrown, you will need to adjust the value of your max bid. For additional help, see Best Coding Practices.

Campaign Optimization Off

When campaign optimization is off, the following rules apply for Variable Minimum Bids. To participate in the marketplace, your max bids must be greater than or equal to the min bids.

Campaign Optimization Off	Content Match (CM)	Sponsored Search (SS)
Campaign	Not Applicable	Not Applicable
Ad Group	(applied at this level) CM max bid must >= CM min bid for the ad group.	SS max bid must be >= SS min bid of any inheriting keyword under this ad group.
Keyword	Not Applicable	(applied at this level) SS max bid must be >= SS min bid for the keyword.

Campaign Optimization On

When campaign optimization is on, the following rules apply for Variable Minimum Bids. To participate in the marketplace, your max bids must be greater than or equal to the min bids.

Campaign Optimization Off	Content Match (CM)	Sponsored Search (SS)
Campaign	max bid must >= CM min bid of any inheriting ad group under this campaign.	max bid must >= SS min bid of any inheriting keyword under this campaign's ad groups.
Ad Group	(applied at this level) CM max bid must >= CM min bid for the ad group.	SS max bid must be >= SS min bid of any inheriting keyword under this ad group.
Keyword	Not Applicable	(applied at this level) SS max bid must >= SS min bid for the keyword.

Market Minimum Bids

The terms for Market Minimum Bids include:

Max bid – maximum bid set by you, the user (EWS optional value).
Min bid – minimum bid set by the system (not available through EWS).
Base bid – base bid established for your market (not available through EWS).

You cannot enter the marketplace with a max bid that is below the base bid; if the max bid is below the base bid, a SOAP fault is thrown. You cannot enter the marketplace with a max bid that is below the min bid if min bids are set for keywords in your market. If the max bid is below the min bid, a SOAP fault is thrown. In either case, if a SOAP fault is thrown, you will need to adjust the value of your max bid. For additional help, see Best Coding Practices.

Note: If min bids are not set for keywords in your market, the base bid applies.

Campaign Optimization Off

When campaign optimization is off, Market Minimum Bids apply to Sponsored Search only. To participate in the marketplace, your Sponsored Search max bids must be greater than or equal to the Sponsored Search min bids.

Campaign Optimization Off	Content Match (CM)	Sponsored Search (SS)
Campaign	Not Applicable	Not Applicable
Ad Group	Not Applicable CM max bid must be >= base bid.	SS max bid must be >= SS min bid for any inheriting keyword under this ad group.
Keyword	Not Applicable	(applied at this level) SS max bid must be >= SS min bid.

Campaign Optimization On

When campaign optimization is on, Market Minimum Bids do not apply. Your max bids must be greater than or equal to the base bid.

Campaign Optimization Off	Content Match (CM)	Sponsored Search (SS)
Campaign	Not Applicable Max bid must be >= base bid.	Not Applicable Max bid must be >= base bid.
Ad Group	Not Applicable CM max bid must be >= base bid.	Not Applicable SS max bid must be >= base bid.
Keyword	Not Applicable	Not Applicable SS max bid must be >= base bid.

Deleting Objects

Use the delete operations to delete a campaign, ad group, ad, or keyword, for example, deleteCampaign or deleteCampaigns. When you delete an object, they are affected as follows:

Campaigns - When you delete a campaign, the status of the campaign is changed to Deleted. The ad groups within that campaign and the ads and keywords within those ad groups will behave as if they are deleted; however, their status is not changed.
Ad Groups - When you delete an ad group, the status of the ad group is changed to Deleted. The ads and keywords within that ad group will behave as if they are deleted; however, their status is not changed.
Ads and Keywords - When you delete an ad or a keyword, the status of the ad or keyword is changed to Deleted. Deleting an ad or keyword does not affect the status of the other ads or keywords in the ad group.

To determine if an object is deleted, create logic to traverse your account hierarchy, beginning at the account level. If you encounter an object whose status is Deleted, you should assume that all the objects under that object will behave as if they are deleted.

Note: Once you delete an object you cannot undelete it.

Including Deleted Objects in Requests

Some "get" operations have an element called "includeDeleted". Setting this element to true will cause the operation to include the deleted objects, or information about the deleted objects in the response.

Purging of Deleted Objects

Deleted items - campaign, ad group, ad, or keyword will be preserved upto a period of 90 days only. After this period, they will be removed permanently and cannot be retrieved using "get" operations that have an element called "includeDeleted". However, purged items will still be displayed in historical reports.

Setting Locales

A locale is the preferred language used for messaging, as in report headers and editorial reason text. In general, the locales for a given market are restricted to the language or languages spoken in that market, one of which will be the default locale, and English. For example, the locales for the JP market are ja_JP (Japanese) and en_JP (English). ja_JP is the default locale.

You can set the locale using the UserManagementService and the addUser, updateMyUserInfo, or updateUserInfo operations or the MasterAccountService and the addNewCustomer operation. It may take up to 15 minutes for the change to take effect. You can also set the locale via the web application and the user preferences option.

Keep in mind that a locale is assigned per user per master account. If you do not specifically set the locale, the default locale for the market is used.

For example, if you use the UserManagementService and the updateMyUserInfo operation to update your user information; you set the locale to en_JP and specify the Japanese master account 1234 in the EWS request. Subsequently, each time you send an EWS request and specify master account 1234, the en_JP locale will be used.

Now, if you use the BasicReportService and the addReportRequestForAccountID operation to run a report; you supply the report information and specify the Japanese master account 5678 in the EWS request. If you have not set the locale for this master account, the default locale, ja_JP, is used. And, if your reports are output in CSV or TSV format, the report elements are translated into Japanese.

To determine which locales apply to your market, see Market-Specific Values.

Getting Started Guide: Service Overviews