update. Yandex Direct API. Version 5

Keywords: managing keywords and autotargetings

update

Changes the parameters of keywords and autotargetings.

Restrictions

Maximum of 1000 objects per method call.

Request

Request structure in JSON format:

{
  "method": "update",
  "params": { /* params */
    "Keywords": [{  /* KeywordUpdateItem */
      "Id": (long), /* required */
      "Keyword": (string), 
      "UserParam1": (string), /* nillable */ 
      "UserParam2": (string), /* nillable */
      "AutotargetingCategories" : [{  /* AutotargetingCategoriesUpdateItem */
        "Category" : ("EXACT"|"ALTERNATIVE"|"COMPETITOR"|"BROADER"|"ACCESSORY") /* required */,
        "Value" : ("YES"|"NO") /* required */
      }, ...],
      "AutotargetingSettings" : {
        "Categories" : {
            "Exact" : ("YES"|"NO"),
            "Narrow" : ("YES"|"NO"),
            "Alternative" : ("YES"|"NO"),
            "Accessory" : ("YES"|"NO"),
            "Broader" : ("YES"|"NO")
        },
        "BrandOptions" : {
            "WithoutBrands" : ("YES"|"NO"),
            "WithAdvertiserBrand" : ("YES"|"NO"),
            "WithCompetitorsBrand" : ("YES"|"NO")
        }
      }
    }, ... ] /* required */
  } 
}

Parameter Type Description Required

Params structure (for JSON) / UpdateRequest structure (for SOAP)

Keywords array of KeywordUpdateItem Keywords and autotargetings to change the parameters for. Yes

KeywordUpdateItem structure

Id long ID of the keyword or autotargeting. Yes

Keyword

string

Keywords.

It can contain negative keywords, which are specified with the minus sign before the word, such as lightning -thunder -rain.

The maximum length of a keyword is 4096 characters. The “!” operator before a negative keyword is not counted in the keyword length (the sequence “-!” counts as a single character).

Maximum of 7 words per keyword, not counting stop words and negative keywords. Each word can have up to 35 characters, not counting the minus sign before a negative keyword.

Attention.

As the result of changing a keyword, a new keyword may be created. See Creating a new keyword after editing.
A keyword may be deleted as the result of updating it, if it became a duplicate of another keyword. See Duplicate keywords.

For autotargeting, the value can't be changed.

UserParam1 string, nillable The value of the {param1} substitution variable. Maximum of 255 characters. No

UserParam2 string, nillable The value of the {param2} substitution variable. Maximum of 255 characters. No

AutotargetingCategories

array of AutotargetingCategoriesUpdateItem

Targeting categories to update.

Attention.

This structure is obsolete and no longer supported. You can't pass both AutotargetingCategories and AutotargetingSettings at the same time. Attempting to do so results in a validation error.

AutotargetingSettings AutotargetingSettingsUpdateItem Targeting settings to update. No

AutotargetingCategoriesUpdateItem structure

Category

AutotargetingCategoriesEnum

Targeting category:

EXACT: The targeted queries. The ad matches user queries.
ALTERNATIVE: Alternative queries. The user is looking for a product that can be replaced by the advertised product. The ad might also match the query in this case.
COMPETITOR: Queries mentioning competitors. Searching competitors for the advertised product.
BROADER: Broad queries. Queries showing interest in a product exemplified by the ad.
ACCESSORY: Related queries. Queries for products that might interest the user in relation to the advertised product or service.

Attention.

This field is deprecated and will soon cease to be supported.

The settings specified using the API are converted for the web interface as follows:


API	Web interface
Enabled EXACT category.	If the Exact and Narrow categories are disabled for the group, Exact and Narrow are enabled. If either or both Exact and Narrow are enabled for the group, no changes are made.
Disabled EXACT category.	If either or both the Exact and Narrow categories are enabled for the group, Exact and Narrow are disabled. If both Exact and Narrow are disabled for the group, no changes are made.
Enabled COMPETITOR category (provided it's the only category enabled).	Enabled “Competitors” brand mention option + the other brand mention options are disabled + all categories are enabled.
Enabled COMPETITOR category (provided it isn't the only category enabled).	Enabled “Competitors” brand mention option.
Disabled COMPETITOR category.	Disabled “Competitors” brand mention option.


API	Web interface
Enabled EXACT category.	If the Exact and Narrow categories are disabled for the group, Exact and Narrow are enabled. If either or both Exact and Narrow are enabled for the group, no changes are made.
Disabled EXACT category.	If either or both the Exact and Narrow categories are enabled for the group, Exact and Narrow are disabled. If both Exact and Narrow are disabled for the group, no changes are made.
Enabled COMPETITOR category (provided it's the only category enabled).	Enabled “Competitors” brand mention option + the other brand mention options are disabled + all categories are enabled.
Enabled COMPETITOR category (provided it isn't the only category enabled).	Enabled “Competitors” brand mention option.
Disabled COMPETITOR category.	Disabled “Competitors” brand mention option.

Yes

Value YesNoEnum The flag indicating that the specified targeting category is enabled. All targeting categories are enabled by default. Yes

AutotargetingSettingsUpdateItem structure

Categories

AutotargetingSettingsCategoriesFieldNames

Targeting categories. Available options:

Exact: Targeted queries. The ad perfectly matches user queries.
Narrow: Narrow queries. The ad is broader than the user's queries.
Alternative: Alternative queries. The user is looking for a product that can be replaced by the advertised product. The ad might also match the query in this case.
Accessory: Related queries. Queries for products that might interest the user in relation to the advertised product or service.
Broader: Broad queries. Queries showing interest in a product exemplified by the ad.

BrandOptions

AutotargetingSettingsBrandOptionsFieldNames

Brand mention settings. Available options:

WithoutBrands: Non-branded queries.
WithAdvertiserBrand: Queries mentioning the advertiser's brand.
WithCompetitorsBrand: Queries mentioning competitor brands.

Parameter Type Description Required

Params structure (for JSON) / UpdateRequest structure (for SOAP)

Keywords array of KeywordUpdateItem Keywords and autotargetings to change the parameters for. Yes

KeywordUpdateItem structure

Id long ID of the keyword or autotargeting. Yes

Keyword

string

Keywords.

It can contain negative keywords, which are specified with the minus sign before the word, such as lightning -thunder -rain.

The maximum length of a keyword is 4096 characters. The “!” operator before a negative keyword is not counted in the keyword length (the sequence “-!” counts as a single character).

Maximum of 7 words per keyword, not counting stop words and negative keywords. Each word can have up to 35 characters, not counting the minus sign before a negative keyword.

Attention.

As the result of changing a keyword, a new keyword may be created. See Creating a new keyword after editing.
A keyword may be deleted as the result of updating it, if it became a duplicate of another keyword. See Duplicate keywords.

For autotargeting, the value can't be changed.

UserParam1 string, nillable The value of the {param1} substitution variable. Maximum of 255 characters. No

UserParam2 string, nillable The value of the {param2} substitution variable. Maximum of 255 characters. No

AutotargetingCategories

array of AutotargetingCategoriesUpdateItem

Targeting categories to update.

Attention.

This structure is obsolete and no longer supported. You can't pass both AutotargetingCategories and AutotargetingSettings at the same time. Attempting to do so results in a validation error.

AutotargetingSettings AutotargetingSettingsUpdateItem Targeting settings to update. No

AutotargetingCategoriesUpdateItem structure

Category

AutotargetingCategoriesEnum

Targeting category:

EXACT: The targeted queries. The ad matches user queries.
ALTERNATIVE: Alternative queries. The user is looking for a product that can be replaced by the advertised product. The ad might also match the query in this case.
COMPETITOR: Queries mentioning competitors. Searching competitors for the advertised product.
BROADER: Broad queries. Queries showing interest in a product exemplified by the ad.
ACCESSORY: Related queries. Queries for products that might interest the user in relation to the advertised product or service.

Attention.

This field is deprecated and will soon cease to be supported.

The settings specified using the API are converted for the web interface as follows:


API	Web interface
Enabled EXACT category.	If the Exact and Narrow categories are disabled for the group, Exact and Narrow are enabled. If either or both Exact and Narrow are enabled for the group, no changes are made.
Disabled EXACT category.	If either or both the Exact and Narrow categories are enabled for the group, Exact and Narrow are disabled. If both Exact and Narrow are disabled for the group, no changes are made.
Enabled COMPETITOR category (provided it's the only category enabled).	Enabled “Competitors” brand mention option + the other brand mention options are disabled + all categories are enabled.
Enabled COMPETITOR category (provided it isn't the only category enabled).	Enabled “Competitors” brand mention option.
Disabled COMPETITOR category.	Disabled “Competitors” brand mention option.


API	Web interface
Enabled EXACT category.	If the Exact and Narrow categories are disabled for the group, Exact and Narrow are enabled. If either or both Exact and Narrow are enabled for the group, no changes are made.
Disabled EXACT category.	If either or both the Exact and Narrow categories are enabled for the group, Exact and Narrow are disabled. If both Exact and Narrow are disabled for the group, no changes are made.
Enabled COMPETITOR category (provided it's the only category enabled).	Enabled “Competitors” brand mention option + the other brand mention options are disabled + all categories are enabled.
Enabled COMPETITOR category (provided it isn't the only category enabled).	Enabled “Competitors” brand mention option.
Disabled COMPETITOR category.	Disabled “Competitors” brand mention option.

Yes

Value YesNoEnum The flag indicating that the specified targeting category is enabled. All targeting categories are enabled by default. Yes

AutotargetingSettingsUpdateItem structure

Categories

AutotargetingSettingsCategoriesFieldNames

Targeting categories. Available options:

Exact: Targeted queries. The ad perfectly matches user queries.
Narrow: Narrow queries. The ad is broader than the user's queries.
Alternative: Alternative queries. The user is looking for a product that can be replaced by the advertised product. The ad might also match the query in this case.
Accessory: Related queries. Queries for products that might interest the user in relation to the advertised product or service.
Broader: Broad queries. Queries showing interest in a product exemplified by the ad.

BrandOptions

AutotargetingSettingsBrandOptionsFieldNames

Brand mention settings. Available options:

WithoutBrands: Non-branded queries.
WithAdvertiserBrand: Queries mentioning the advertiser's brand.
WithCompetitorsBrand: Queries mentioning competitor brands.

Response

Response structure in JSON format:

{
  "result": {  /* result */
    "UpdateResults": [{  /* ActionResult */
      "Id": (long),
      "Warnings": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
       }, ...
      ],
      "Errors": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
       }, ...
      ] 
    }, ... ] /* required */
  }
}


Result structure (for JSON) / UpdateResponse structure (for SOAP)
Parameter	Type	Description
`UpdateResults`	array of ActionResult	Results of changing parameters of keywords and autotargetings.
ActionResult structure
`Id`	long	ID of the changed keyword or autotargeting. Returned if there are no errors, see Operations on object arrays.
`Warnings`	array of ExceptionNotification	Warnings that occurred during the operation.
`Errors`	array of ExceptionNotification	Errors that occurred during the operation.


Result structure (for JSON) / UpdateResponse structure (for SOAP)
Parameter	Type	Description
`UpdateResults`	array of ActionResult	Results of changing parameters of keywords and autotargetings.
ActionResult structure
`Id`	long	ID of the changed keyword or autotargeting. Returned if there are no errors, see Operations on object arrays.
`Warnings`	array of ExceptionNotification	Warnings that occurred during the operation.
`Errors`	array of ExceptionNotification	Errors that occurred during the operation.

Was the article useful?

Please tell us what you didn't like about this article:

suspend

KeywordsResearch: preprocessing of keywords

Contents

Restrictions Request Response

suspend

KeywordsResearch: preprocessing of keywords