Send keywords to SVCS

The SerpstatTaskProcedure.addKeywordListFreq method sends keywords to volume parsing and returns a unique task key to be used for SerpstatTaskProcedure.getTaskResult to get parsing results. Keywords must be transferred as an array.

General request parameters and instructions for using Serpstat API

Request parameters
Parameter	Description	Type	Optional	Default value	Value Options
id	Identifier of current request	string	no		1, test
method	API method name	string	no		SerpstatTaskProcedure.addKeywordListFreq
params	Object with parameters	object	no
keywords	Keywords (max amount - 50 000	array	no		["iphone", "iphone X"]
se id	Search base	string	yes	1	1 - google 2 - yandex
type Id	Device id type	int	yes	1	1 - desktop 2 - mobile
region Id	Region or city id for Google or Yandex Region is indicated in the document.	int	no
match	Type match id (Yandex only)	string	yes	exact	exact - doesn’t care about word order but does care about word form. Example: “!buy in instalments!” extra - cares about both word form and order. Example: “[!buy!in instalments]” phrase - anything that contains these words in a different order or word form will do. Example: “to buy an elephant in instalments” wide - wide match with the fixed word form. Example: “an elephant in instalments” wide-fixed - wide match with the fixed word form. Example: “an elephant in instalments”

Response parameters
Parameter	Description	Type
id	Response id corresponds the request id	int
result	Contains the answer	array
task Id	Query id to get parsing results with SerpstatTaskProcedure.getTaskResult	string
accepted	Total number of keywords set for parsing excluding blocked	int
duplicates_cleaned	The number of duplicated keywords that have been cleared, the credits for them will not be charged.	int
blocked	Array with blocked keywords. Credits are not charged.	array

Keywords block
Some keywords will get to blocked array in the method’s response because there’s no volume checking for keywords containing the following search operators:
- site:
- related:
- info:
- cache:
- OR
- url:
- inurl:

Additional for Yandex:
- title:
- rhost:
- host:
- domain:
- mime:
- lang:
- date:
- cat:

Keywords cleaning for special elements
Special elements are deleted from unblocked keywords.

A list of prohibited special elements:

(

)

;

Volume issue block for search engine
Keywords may not pass the volume checking for a search engine. The keywords’ subject that won’t pass checking:
- for Google
- for Yandex
If the keyword failed a search engine check, SerpstatTaskProcedure.getTaskResult method will fill the status field for a keyword with value 4.

Credits:
This method corresponds to specific limits. You will find conditions and price details following this link.

Example

Request data:

{
"id": "1" ,
"method": "SerpstatTaskProcedure.addKeywordListFreq",
"params": { 
    "keywords": ["iphone", "iphone X", "iphone 10", "iphone 11", "iphone 12", "iphone 13"],
    "typeId": 1, 
    "seId": 1,
    "regionId": 2840
     }
}

Response data:

{
    "id": "1",
    "result": {
        "taskId": "bc0a46cc-357e-4706-a674-1e8166f81fb2",
        "accepted": 6,
        "duplicates_cleaned": 0,
        "blocked": []
    }
}