deduplicate

Performs preprocessing on an array of keywords.

  1. Request
  2. Response
  3. Example

This method performs the following actions with keywords:

Unifying duplicate keywords

Joins together multiple keywords that differ only in the negative keywords, word form, or presence of stop words. The unified keyword contains the negative keywords from all the original keywords. For example, the keywords custom windows -cheap and custom window -blinds would be replaced with the single keyword phrase custom window -cheap -blinds. In addition, duplicate keywords are deleted when joining keywords.

Differentiating overlapping keywords

Adds a negative keyword if the keyword is contained in another keyword phrase that differs by just one word. An example is the keywords coat and fur coat. A negative keyword will be added to the first keyword, resulting in coat -fur. This means that a search query for fur coats will match only one of the keywords, not both.

The method accepts an input array that can contain:

  • New keywords without an ID.
  • Existing keywords that have an ID in Yandex.Direct or an external database.

As the result of unifying duplicates and differentiating overlapping keywords, the method returns instructions about which keywords to add, change, or delete. The response format is as close as possible to the request format for the add, update and delete methods in the Keywords service.

Request

Request structure in JSON format:

{
  "method": "deduplicate",
  "params": { /* params */
    "Keywords": [ {  /* DeduplicateRequestItem */
      "Id": (long),
      "Keyword": (string), /* required */
      "Weight": (long)
    }, ... ], /* required */
    "Operation": [( MERGE_DUPLICATES | ELIMINATE_OVERLAPPING ), ... ]
  } 
}

Parameters are described below.

ParameterTypeDescriptionRequired
Params structure (for JSON) / DeduplicateRequest structure (for SOAP)
Keywordsarray of DeduplicateRequestItemKeywords to pre-preprocess. Maximum of 400,000 items in the array.Yes
Operationarray of DeduplicateOperationEnumOperations to perform on an array of keywords:
  • MERGE_DUPLICATES — Unifying duplicate keywords.
  • ELIMINATE_OVERLAPPING — Differentiating overlapping keywords.

If this parameter is omitted, both operations are performed.

No
DeduplicateRequestItem structure
IdlongThe keyword ID in Yandex.Direct or in an external database.No
Keywordstring

Keywords. Can contain negative keywords and operators.

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.

Yes
Weightlong

Weight of the keyword. Positive integer.

If multiple keywords are joined together, the keyword with the highest weight is kept or is modified, and the others are deleted.

No

Response

Response structure in JSON format:

{
  "result": { /* result */
    "Add": [{ /* DeduplicateResponseAddItem */
      "Keyword": (string) /* required */
    }, ... ],
    "Update": [{ /* DeduplicateResponseUpdateItem */
      "Id": (long), /* required */
      "Keyword": (string) /* required */
    }, ... ],
    "Delete": { /* IdsCriteria */
      "Ids": [(long), ... ] /* required */
    },
    "Failure": [{ /* DeduplicateErrorItem */
      "Position": (long), /* required */
      "Warnings": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ],
      "Errors": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ] 
    }, ... ]
  }
}

Parameters are described below.

ParameterTypeDescription
result structure (for JSON) / DeduplicateResponse structure (for SOAP)
Addarray of DeduplicateResponseAddItemKeywords that can be input to the Keywords.add method.
Updatearray of DeduplicateResponseUpdateItemKeywords that can be input to the Keywords.update method.
DeleteIdsCriteriaKeywords that can be input to the Keywords.delete method.
Failurearray of DeduplicateErrorItemKeywords that weren't processed due to an error.
DeduplicateResponseAddItem structure
KeywordstringA keyword to add.
DeduplicateResponseUpdateItem structure
IdlongKeyword ID from the request.
KeywordstringChanged keyword.
IdsCriteria structure
Idsarray of longIDs of keywords to delete.
DeduplicateErrorItem structure
PositionlongThe sequential number of the keyword in the input array (starting from 1).
Warningsarray of ExceptionNotification

Warnings that were issued when processing the keyword.

Errorsarray of ExceptionNotification

Errors that occurred when processing the keyword.

Example

Request
{
  "method": "deduplicate",
  "params": {
    "Keywords": [{
      "Keyword": "A B -C"
    },
    {
      "Id": 1000,
      "Keyword": "A B -D"
    },
    {
      "Id": 1001,
      "Keyword": "A B"
    },
    {
      "Keyword": "E F"
    }]
  }
}
Response

The keywords A B -C, A B -D and A B are joined together into the combined keyword A B -C -D:

  • The keyword A B -C is new. It doesn't need to be added because the same one already exists in the database. It is skipped in the response.
  • The keyword A B -D exists in the database, so it needs to be replaced with the combined keyword. The keyword ID and new value are returned in the Update structure.
  • The A B keyword exists in the database and it needs to be deleted. The keyword ID is returned in the Delete structure.

The E F keyword is new and needs to be added. It is returned in the Add structure.

{
  "result": {
    "Add": [{
      "Keyword": "E F"
    }],
    "Update": [{
      "Id": 1000,
      "Keyword": "A B -C -D"
    }],
    "Delete": {
      "Ids": [ 1001 ]
    }
  }
}