Keyword

A keyword determines which search queries on Yandex will trigger an ad impression, as well as the topics of pages and user interests that the ad will be displayed for in ad networks (the Yandex Advertising Network and external networks). For more information, see Keywords in the Help for Yandex Direct.

A keyword may contain negative keywords. You can also set negative keywords at the ad group level and at the campaign level. See Negative keywords.

A keyword can contain refining operators. See Symbols and operators in Yandex Direct Help.

Servicing

Use the Keywords service for managing keywords.

Methods

add | update | delete | suspend | resume | get

Restrictions

You cannot add keywords to an ad group of the CPM_BANNER_AD_GROUP type and USER_PROFILE subtype, as well as an ad group of the DYNAMIC_TEXT_AD_GROUP type.

To get the limit on the number of keywords per ad group for an advertiser, use the Clients.get or AgencyClients.get method (see the KEYWORDS_TOTAL_PER_ADGROUP element in the Restrictions array).

For restrictions on the number of words and characters in a keyword, see the section Quantitative restrictions in the Help for Yandex Direct.

Status and state of a keyword

The Status parameter reflects the results of reviewing a keyword.

Status	Description
DRAFT	New keyword: not yet submitted for review, or currently under review. If a campaign has at least one ad that is active or submitted for review, new keywords are automatically submitted for review.
ACCEPTED	The keyword was accepted after review.
REJECTED	The keyword was rejected after review.
UNKNOWN	The status is unknown. This value is used for backward compatibility and for displaying statuses that are not supported in this version of the API.

The State parameter reflects whether displays were suspended for the keyword.

State	Description
ON	Ad displays for the keyword are enabled.
SUSPENDED	Ad displays were suspended by the owner using the suspend method or in the web interface.
OFF	The keyword has not been submitted for review yet, or was rejected after review.

The ServingStatus parameter reflects the ad group serving status. See Ad group serving status.

Learn more

• How can I tell if there are active displays for a keyword?

Substitution variables

The ad link and sitelinks can use the substitution variables {param1} and {param2}. They are substituted with the values specified in the keyword parameters UserParam1 and UserParam2. This allows you to modify links depending on the keyword used to select and display the ad. For more information about substitution variables, see Transferring ad data in URLs in Yandex Direct Help.

Creating a new keyword after editing

A new keyword may be created as the result of editing a keyword. For example, this may happen if you delete or replace a keyword or delete a negative keyword, or add or remove the ! or + operator.

If a new keyword is created, the update method returns the ID of the new keyword and a warning.

Statistics will still be available for the “old” keyword, but displays will be stopped for it, and you will not be able to work with it anymore.

Duplicate keywords

Duplicates are keywords that differ only in their word forms and auxiliary parts of speech, such as exchange dollars to rubles and exchanging rubles and dollars.

The add and update methods automatically delete duplicate keywords within an ad group:

• If two keywords that are duplicates are passed in the input array of the add method, a single keyword is created, identical IDs are returned in the method response, and a warning is issued for one of the keywords.

• If the input array of the add method passes a keyword that duplicates an existing one, the new keyword isn't created, and the method response returns the ID of the existing keyword with a warning.

• If editing a keyword using the update method caused the keyword to become a duplicate of an existing one, the edited keyword is deleted and the method response returns the ID of the existing keyword with a warning.

• If editing two keywords using the update method causes the keywords to become duplicates, one of them is deleted. The response for it returns the ID of the other keyword with a warning.

  Example

  

• If editing two keywords using the update method causes the keywords to become duplicates and a new keyword is created, the method returns the ID of the new keyword and warnings: for one of the keywords in the request, that a new keyword was created, and for the other, that the same keyword exists.

  Example