Keyword Data Object - Campaign Management

Defines a keyword.

Keywords are the words or phrases searched on when looking for a product or service. For example, keywords could be any of the following:

  • Shoes
  • Boats cruises vacation
  • Tennis lessons in New York

As shown above, a keyword can be just a single word, several words, or even a phrase. In the context of search advertising, all of these are simply referred to as a keyword.

Syntax

<xs:complexType name="Keyword" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:sequence>
    <xs:element minOccurs="0" name="Bid" nillable="true" type="tns:Bid" />
    <xs:element minOccurs="0" name="BiddingScheme" nillable="true" type="tns:BiddingScheme" />
    <xs:element minOccurs="0" name="DestinationUrl" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="EditorialStatus" nillable="true" type="tns:KeywordEditorialStatus" />
    <xs:element minOccurs="0" name="FinalAppUrls" nillable="true" type="tns:ArrayOfAppUrl" />
    <xs:element minOccurs="0" name="FinalMobileUrls" nillable="true" type="q27:ArrayOfstring" xmlns:q27="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
    <xs:element minOccurs="0" name="FinalUrlSuffix" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="FinalUrls" nillable="true" type="q28:ArrayOfstring" xmlns:q28="http://schemas.microsoft.com/2003/10/Serialization/Arrays" />
    <xs:element minOccurs="0" name="ForwardCompatibilityMap" nillable="true" type="q29:ArrayOfKeyValuePairOfstringstring" xmlns:q29="http://schemas.datacontract.org/2004/07/System.Collections.Generic" />
    <xs:element minOccurs="0" name="Id" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="MatchType" nillable="true" type="tns:MatchType" />
    <xs:element minOccurs="0" name="Param1" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Param2" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Param3" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Status" nillable="true" type="tns:KeywordStatus" />
    <xs:element minOccurs="0" name="Text" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="TrackingUrlTemplate" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="UrlCustomParameters" nillable="true" type="tns:CustomParameters" />
  </xs:sequence>
</xs:complexType>

Elements

Element Description Data Type
Bid The highest price that you want to pay each time someone clicks your ad.

In addition to setting a default ad group level bid, you can set custom bids for each keyword. If you set a custom bid for a particular keyword, this bid amount will override the default bid set for your ad group. We recommend custom bidding for advanced advertisers who want more control of their pay-per-click rates.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed. To delete the keyword bid and use the AdGroup default match type bid, set the Amount element of the Bid object to null.
Bid
BiddingScheme The bid strategy type for how you want to manage your bids.

For keywords you can use either of the InheritFromParentBiddingScheme or ManualCpcBiddingScheme objects. For details about supported bid strategies per campaign type, see Budget and Bid Strategies.

IMPORTANT: If the campaign bid strategy type is set to MaxClicks, MaxConversions, or TargetCpa, the behavior of existing features will change unless you set an individual ad group's or keyword's bid strategy to ManualCpc.
- You can continue to set the ad group and keyword bids; however they will not be used by Microsoft Advertising.
- Microsoft Advertising will periodically change your stored ad group or keyword bid settings. You can continue to set new bids, however Microsoft Advertising may change them at any time using this bid strategy type.
- You can continue to set bid adjustments e.g. for age, gender, or location; however, the multiplier will inform rather than directly modify or override the automated bid. For auto bidding the multiplier is used as a weighted percentage to inform Microsoft Advertising about how much you value the criterion relative to other criteria. For example, a -50% bid multiplier for a mobile device criterion with the Max Conversions bid strategy to indicate that you value conversions from mobile traffic half as much as other device types. The same bid multiplier with the Max Clicks bid strategy would indicate that you value clicks on mobile half as much as other device types. The valid range of values that you can use to inform auto bidding is -100.00 through 30.00.

Tip: You can set your campaign's bid strategy to EnhancedCpcBiddingScheme, MaxClicksBiddingScheme, MaxConversionsBiddingScheme, or TargetCpaBiddingScheme and then, at any time, set an individual ad group's or keyword's bid strategy to Manual CPC (ManualCpcBiddingScheme).

This element is not supported for campaigns of type Shopping.

Add: Optional. If you do not set this element, then InheritFromParentBiddingScheme is used by default.
Update: Optional. If no value is set for the update, this setting is not changed.
BiddingScheme
DestinationUrl The URL of the webpage to take the user to when they click the ad. The keyword's destination URL is used if specified; otherwise, the ad's destination URL is used.

Important: As of November 2018 the keyword destination URL cannot be added or updated. You can use Final URLs instead. For more details see Migrating your keyword destination URLs to final URLs.

Add: Not allowed
Update: Not allowed
string
EditorialStatus The editorial review status of the keyword, which indicates whether the keyword is pending review, has been approved, or has been disapproved.

Add: Read-only
Update: Read-only
KeywordEditorialStatus
FinalAppUrls Reserved for future use. AppUrl array
FinalMobileUrls The mobile landing page URL. The keyword's final mobile URL is used if specified; otherwise, the ad's final mobile URL is used.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.
string array
FinalUrls The landing page URL. The keyword's final URL is used if specified; otherwise, the ad's final URL is used.

The following validation rules apply to Final URLs and Final Mobile URLs.
- The length of the URL is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit.
- You may specify up to 10 items for both FinalUrls and FinalMobileUrls; however, only the first item in each list is used for delivery. The service allows up to 10 for potential forward compatibility.
- Usage of '{' and '}' is only allowed to delineate tags, for example {lpurl}.
- Final URLs must each be a well-formed URL starting with either http:// or https://.
- If you specify FinalMobileUrls, you must also specify FinalUrls.
- You may not specify FinalMobileUrls if the device preference is set to mobile. Also note that if the TrackingUrlTemplate or UrlCustomParameters elements are set, then at least one final URL is required. For more information, see URL Tracking with Upgraded URLs.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.
string array
FinalUrlSuffix The final URL suffix can include tracking parameters that will be appended to the end of your landing page URL. We recommend placing tracking parameters that your landing page requires in a final URL suffix so that your customers are always sent to your landing page. For more details and validation rules see Final URL Suffix in the technical guides.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.
string
ForwardCompatibilityMap The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version.

Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for this object.
KeyValuePairOfstringstring array
Id The system-generated identifier of the keyword.

Add: Read-only
Update: Required
long
MatchType The type of match to compare the keyword and the user's search term.

Add: Required
Update: Read-only
MatchType
Param1 The string to use as the substitution value in an ad if the ad's title, text, display URL, or destination URL contains the {Param1} dynamic substitution string.

Although you can use {Param1} to specify an ad's destination URL, you are encouraged not to. Instead, you should set the keyword's DestinationUrl element.

The string can contain a maximum of 1,022 characters. The actual limit depends on the length of the element that references the substitution string. For example, the length of a text ad's title can contain a maximum of 25 characters.

When implementing dynamic text in your ad copy you should provide a default string e.g. {Param1:default} that the system will use if Param1 for a keyword is null or empty, or if including the Param1 substitution value will cause the expanded string to exceed the element's limit; otherwise the ad will not serve with this keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters.

Also note that if the ad group only has one ad, and if that ad uses {Param1} but does not provide a default string e.g. {Param1:default}, then you must supply a valid Param1 value for that substitution. Otherwise this keyword cannot be added or updated.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.
string
Param2 The string to use as the substitution value in an ad if the title, text, display URL, or destination URL contains the {Param2} dynamic substitution string.

Typically, you use the {Param2} substitution string in the title or text (ad copy description) elements of an ad.

The string can contain a maximum of 70 characters. The actual limit depends on the length of the element that references the substitution string. For example, the length of a text ad's title can contain a maximum of 25 characters.

When implementing dynamic text in your ad copy you should provide a default string e.g. {Param2:default} that the system will use if Param2 for a keyword is null or empty, or if including the Param2 substitution value will cause the expanded string to exceed the element's limit; otherwise the ad will not serve with this keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters.

Also note that if the ad group only has one ad, and if that ad uses {Param2} but does not provide a default string e.g. {Param2:default}, then you must supply a valid Param2 value for that substitution. Otherwise this keyword cannot be added or updated.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.
string
Param3 The string to use as the substitution value in an ad if the title, text, display URL, or destination URL contains the {Param3} dynamic substitution string.

Typically, you use the {Param3} substitution string in the title or text (ad copy description) elements of an ad.

The string can contain a maximum of 70 characters. The actual limit depends on the length of the element that references the substitution string. For example, the length of a text ad's title can contain a maximum of 25 characters.

When implementing dynamic text in your ad copy you should provide a default string e.g. {Param3:default} that the system will use if Param3 for a keyword is null or empty, or if including the Param3 substitution value will cause the expanded string to exceed the element's limit; otherwise the ad will not serve with this keyword. For more information, see the Microsoft Advertising help article Automatically customize your ads with dynamic text parameters.

Also note that if the ad group only has one ad, and if that ad uses {Param3} but does not provide a default string e.g. {Param3:default}, then you must supply a valid Param3 value for that substitution. Otherwise this keyword cannot be added or updated.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.
string
Status The keyword's status. By default, the status is set to Active.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.
KeywordStatus
Text The keyword text. The text can contain a maximum of 100 characters. You should specify the keyword in the locale of the Language value that you specified for the ad group to which the keyword belongs.

Add: Required
Update: Read-only
string
TrackingUrlTemplate The tracking template to use as a default for all FinalUrls and FinalMobileUrls.

The following validation rules apply to tracking templates. For more details about supported templates and parameters, see the Microsoft Advertising help article What tracking or URL parameters can I use?
- Tracking templates defined for lower level entities e.g. ads override those set for higher level entities e.g. campaign. For more information, see Entity Hierarchy and Limits.
- The length of the tracking template is limited to 2,048 characters. The HTTP or HTTPS protocol string does count towards the 2,048 character limit.
- The tracking template must be a well-formed URL beginning with one of the following: http://, https://, {lpurl}, or {unescapedlpurl}.
- Microsoft Advertising does not validate whether custom parameters exist. If you use custom parameters in your tracking template and they do not exist, then the landing page URL will include the key and value placeholders of your custom parameters without substitution. For example, if your tracking template is http://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} and neither {_season} or {_promocode} are defined at the campaign, ad group, criterion, keyword, or ad level, then the landing page URL will be the same.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed.
string
UrlCustomParameters Your custom collection of key and value parameters for URL tracking.

Microsoft Advertising will accept the first 8 CustomParameter objects that you include within the CustomParameters object, and if you include more than 8 custom parameters an error will be returned. Each CustomParameter includes Key and Value elements.

Add: Optional
Update: Optional. If no value is set for the update, this setting is not changed. Set the UrlCustomParameters element to null or empty to retain any existing custom parameters. To remove all custom parameters, set the Parameters element of the CustomParameters object to null or empty. To remove a subset of custom parameters, specify the custom parameters that you want to keep in the Parameters element of the CustomParameters object.
CustomParameters

Requirements

Service: CampaignManagementService.svc v13
Namespace: https://bingads.microsoft.com/CampaignManagement/v13

Used By

AddKeywords
GetKeywordsByAdGroupId
GetKeywordsByEditorialStatus
GetKeywordsByIds
UpdateKeywords