The service overviews provide conceptual information about the Marketing API services. This information supplements the more detailed information available in the Marketing API Reference. Features that span more than one service are discussed in separate topics.
The Marketing API service overviews include:
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:
Content Match displays your ads on web pages with articles, reviews, news or other content that is relevant to your titles and descriptions.
Use the sponsoredSearchON, advancedMatchON, and contentMatchON elements to enable (set to true) or disable (set to false) tactics:
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, however, that the sponsoredSearchON element and the contentMatchON element cannot both set disabled at the same time. Either the sponsoredSearchON element and/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:
| 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 |
The following examples show how different tactic settings affect campaigns, ad groups, and keywords.
Example 1:
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:
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 |
Bids represent the maximum 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 index (quality score) 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).
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 min bids are not the same for each system.
The terms for Variable Minimum Bids include:
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. |
The terms for Market Minimum Bids include:
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. |
Use the delete operations to delete a campaign, ad group, ad, or keyword (for example, deleteCampaign or deleteCampaigns). When you delete an object, the objects within that object are affected as follows:
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 un-delete it.
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.
Deleted items (campaign, ad group, ad, or keyword) will be preserved for 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.
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, suppose 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, suppose 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 (column names) are translated into Japanese.
To determine which locales apply to your market, see Market-Specific Values.