Open API SpySERP.com

General Principles

Open SpySERP API available at the next link: https://spyserp.com/panel/api. If description does not specify the use of “POST”, then the query parameters could be referred through the method “GET”.

Using the “POST” method, all the arrays of parameters should be in json. Using any method call, the server transfer all the data in JSON-format. The call should transfer “GET”-parameter token with an access token received from the user profile page.

Using the “GET” method, API call method name is appended after the API link, for example: https://spyserp.com/panel/api/keywords. Transferring manner for the “GET”-parameters doesn’t matter. If the response code wouldn’t be 200 as a result of the processing request, then the error text will be displayed at the status_msg field.

If under the method call server transfer a data set by pages, then the parameters for such method may be page and pageSize (the number of elements on the page). A server transfer the array contains all the data for the current page in the element with items key. totalCount and page elements contains the whole number of the current elements and current page, respectively.

If the parameter description doesn’t contain the direct reference that this parameter is required, then there is no need to transfer it to the query (the default will be used).

Common methods

searchEngines

Request example:

{
    "token": "yourApiKey",
    "method":"searchEngines",
    "withSettingValues":1
}

Response example:

{
    "1": {
        "id": 1,
        "name": "Google",
        "url": "google.com",
        "type": "SE::Google",
        "editable_settings": {
            "google_domains": {
                "result_key": "domain",
                "label": "Domain",
                "value": "www.google.com"
            },
            ...
        },
        "setting_values": {
            "google_domains": {
                "values": {
                    "www.google.com": "www.google.com",
                    ...
                 },
                "long": 0
            },
            ...
        },

Make sure you replace "yourApiKey" with your API token!

List of all active SE SpySERP with Parameters

Request Parameters:

Parameter	Description
withSettingValues	0 by default. If withSettingValues = 1, then array for each search engine transfer in the setting_values field the data for each setting. If the parameter long=1, then the data wouldn’t transferred, and you can receive it with the searchEnginesLoadSettings method.

Response Parameters:

Search engines IDs are the element keys in the arrays.

Parameter	Description
name	Search Engine name
url	SE URL
type	SE type (in the A-Parser)
editable_settings	E editable settings
setting_values	Optional. The values for each editable_settings settings, when long=0.

searchEnginesLoadSettings

Request example:

{
    "token": "yourApiKey",
    "method":"searchEnginesLoadSettings",
    "key":"google_location",
    "search":"Moscow"
}

Response example:

{
    "Moscow,Pennsylvania,United States": "Moscow,Pennsylvania,United States",
    "Moscow Oblast,Russia": "Moscow Oblast,Russia",
    "Moscow,Russia": "Moscow,Russia",
    ...
}

Make sure you replace "yourApiKey" with your API token!

Value search for one parameter of the search engine

Request Parameters:

Parameter	Description
key	(required). The setting for which values are derived for
search	the search word for existing values of the parameter

projectFrequencyYandexConformity

Request example:

{
    "token": "yourApiKey",
    "method":"projectFrequencyYandexConformity"
}

Response example:

{
    "Freq": "Basic: apple store",
    "\"Freq\"": "Phrase: \"apple store\"",
    ...
}

Make sure you replace "yourApiKey" with your API token!

Returns the list of the permissible matching types for Yandex frequency

Exact user's methods

balance

Request example:

{
    "token": "yourApiKey",
    "method":"balance"
}

Response example:

{
    "rub": 1000,
    "usd": 120
}

Make sure you replace "yourApiKey" with your API token!

Current user balance in all types of currencies

projects

Request example:

{
    "token": "yourApiKey",
    "method":"projects"
}

Response example:

{
    "groups": {
        "0": {
            "groupTitle": "",
            "projects": [
                {
                    "id": 21,
                    "name": "My project",
                    "created_at": 1468935137000,
                    "disabled": 2,
                    "domains": [
                        {
                            "title": "google.com",
                            "domain_id": 1,
                            "average": "0",
                            "top3": "0",
                            "top10": "0",
                            "top30": "0",
                            "up": "0",
                            "down": "0",
                            "middle": "0"
                        },
                        ...

Make sure you replace "yourApiKey" with your API token!

List of current user projects, divided by groups

Response Parameters:

Parameter	Description
groups	projects group array. If the user didn’t create groups, all the projects placed in the default group with id=0
groupTitle	Group title
projects	projects group array
name	project name
created_at	project creation timestamp
disabled	project status (disabled - 1, enabled - 2)
domains	data set scan of the last processed project for each domain. Average - average position value, top3 - number of keywords in top-3, top-10 - number of keywords in top-10, up - number of keywords raised from the last check, down - number of keywords dropped down from the last check, middle - number of keywords with stable positions

messages

Request example:

{
    "token": "yourApiKey",
    "method":"messages"
}

Response example:

{
    "items": [
        {
            "id": 3802,
            "type": 0,
            "created_at": 1510115461,
            "visited_at": 0,
            "subject": "Project #1",
            "content": "The parsing is complete"
        },
        ...
    ],
    "totalCount": 120,
    "page": 0
}

Make sure you replace "yourApiKey" with your API token!

User messages`

Request Parameters:

Parameter	Description
page	0 by default
pageSize	20 by default, not more than 300

Response Parameters:

Parameter	Description
items	messages array
items.created_at	timestamp for created message
items.visited_at	timestamp for viewed message
items.subject	subject of message
items.content	message text
totalCount	total number of messages
page	current page

timeline

Request example:

{
    "token": "yourApiKey",
    "method":"timeline"
}

Response example:

{
    "6923": {
        "project_name": "My project",
        "project_id": 467,
        "id": 6923,
        "data": {
            "up": {
                "vk.com": 47
            },
            "vis": {
                "vk.com": 169
            },
            "down": {
                "vk.com": 83
            },
            "top3": {
                "vk.com": 2
            },
            "top10": {
                "vk.com": 11
            },
            "top30": {
                "vk.com": 97
            },
            "middle": {
                "vk.com": 39
            },
            "average": {
                "vk.com": "30"
            }
        },
        "time_completed": 1508713648,
        "schedule_domains": [
            295
        ]
    },
    ...

Make sure you replace "yourApiKey" with your API token!

List of the latest parsed reports for all user’s projects with the data set scan

Response Parameters:

The array with the projects id keys sorted by newest to oldest transferred from the server

Parameter	Description
project_name	project name
project_id	project id
data	data set scan divided by personal project domains. Average - average position value, top3 - number of keywords in top-3, top-10 - number of keywords in top-10, up - number of keywords raised from the last check, down - number of keywords dropped down from the last check, middle - number of keywords with stable positions
time_completed	timestamp of the completed parsing process
schedule_domains	set of domains for which statistical data was received

package

Request example:

{
    "token": "yourApiKey",
    "method":"package"
}

Response example:

{
    "package": "Expert",
    "time_finish": "21.09.2025"
}

Make sure you replace "yourApiKey" with your API token!

Information about current user’s package

Response Parameters:

Parameter	Description
package	package name
time_finish	package expiring data

project

Request example:

{
    "token": "yourApiKey",
    "method":"project",
    "project_id":1540,
    "withSettingValues":1
}

Response example:

{
    "id": 21,
    "name": "My project",
    "created_at": 1468935137,
    "disabled": 2,
    "group_id": 0,
    "check_type": 3,
    "settings": {
        "parsing_notification": {
            "value": 0,
            "title": "Parsing notification"
        },
        "openstat": {
            "value": 1,
            "title": "Openstat"
        },
        "parseAnchor": {
            "value": 0,
            "title": "Parse anchors and snippets"
        }
    }
}

Make sure you replace "yourApiKey" with your API token!

Check information for separate project

Request Parameters:

Parameter	Description
project_id	(required). Project ID
withSettings	if 1, then additional project settings will be transferred

Response Parameters:

Parameter	Description
Name	project name
Created_at	timestamp for creation date
Disabled project status (1	disabled, 2
Group_id	project group ID
Check_type	type of data parsing (1
Settings	(optional). Current project settings (parsing_notification

projectCreate

Request example:

{
    "token": "yourApiKey",
    "method":"projectCreate",
    "name":"My new project",
    "group_id":2
}

Response example:

{
    "success": true,
    "project_id": 526
}

Make sure you replace "yourApiKey" with your API token!

Project Creation

Request Parameters:

Parameter	Description
Name	(required). Project name
Group_id	0 by default. Group ID for the project. If not specified or 0, then project doesn’t have any group

Response Parameters:

Parameter	Description
project_id	New project ID

projectDelete

Request example:

{
    "token": "yourApiKey",
    "method":"projectDelete",
    "project_id":526
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Project delete

projectDisable

Request example:

{
    "token": "yourApiKey",
    "method":"projectDisable",
    "project_id":7
}

Response example:

{
    "success": true,
    "status": 1
}

Make sure you replace "yourApiKey" with your API token!

Change project status - Active or not.

Request Parameters:

Parameter	Description
project_id	(required) Project ID

Response Parameters:

Parameter	Description
status	current project status (1 - active, 2 - not active)

projectGroupChange

Request example:

{
    "token": "yourApiKey",
    "method":"projectDisable",
    "project_id":7,
    "group_id":9
}

Response example:

{
    "success": true,
}

Make sure you replace "yourApiKey" with your API token!

Change project group

Request Parameters:

Parameter	Description
* project_id	(required) Project ID
* group_id	(required) New group ID

projectRename

Request example:

{
    "token": "yourApiKey",
    "method":"projectRename",
    "project_id":448,
    "name":"New project name"
}

Response example:

{
    "success": true,
}

Make sure you replace "yourApiKey" with your API token!

Project rename

Request Parameters:

Parameter	Description
project_id	(required) Project ID
name	(required) New project name

projectPasteManual

Request example:

{
    "token": "yourApiKey",
    "method":"projectPasteManual",
    "project_id":448
}

Response example:

{
    "success": true,
    "parsed_schedule_id": 398445
}

Make sure you replace "yourApiKey" with your API token!

Manual project parsing

Request Parameters:

Parameter	Description
project_id	(required) Project ID

projectsSettings

Request example:

{
    "token": "yourApiKey",
    "method":"projectsSettings"
}

Response example:

{
    "sort_statistic": "reverse",
    "show_chart": "1",
    "display_number": "1",
    "show_link": "1",
    "display_average": "domain",
    "backlight_url": "yes",
    "display_statistic_numbers": "1"
}

Make sure you replace "yourApiKey" with your API token!

Receive all settings of all user projects

Response Parameters:

Response parameters: alias settings are the keys of the transferring array, and the elements are the settings values.

projectsSettingsChange

Request example:

{
    "token": "yourApiKey",
    "method":"projectsSettingsChange",
    "setting":"show_chart",
    "value":"0"
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Change settings for all user projects

Request Parameters:

Parameter	Description
setting	(required) alias (name) of the setting
value	(required) new setting value

projectsSettingValues

Request example:

{
    "token": "yourApiKey",
    "method":"projectsSettingValues",
    "setting":"show_chart"
}

Response example:

{
    "0": "Not Show",
    "1": "Show"
}

Make sure you replace "yourApiKey" with your API token!

Receive possible settings values from all user projects

Request Parameters:

Parameter	Description
setting	(required) alias setting

Response Parameters:

Response parameters: possible values are the keys of the transferring array, and the elements are their names

groups

Request example:

{
    "token": "yourApiKey",
    "method":"groups"
}

Response example:

{
    "items": [
        {
            "id": 56,
            "name": "Group 1",
            "projectscount": 1
        },
        {
            "id": 43,
            "name": "Bad projects",
            "projectscount": 9
        },
        ...
    ],
    "totalCount": 11,
    "page": 0
}

Make sure you replace "yourApiKey" with your API token!

List of all user projects groups

Request Parameters:

Parameter	Description
page	0 by default
pageSize	20 by default, no more than 20

Response Parameters:

Parameter	Description
items	user groups array
items.name	group name
items.projectscount	number of projects per group
totalCount	total number of groups
page	current page

groupAdd

Request example:

{
    "token": "yourApiKey",
    "method":"groupAdd",
    "group":"New group"
}

Response example:

{
    "success": true,
    "id": 73
}

Make sure you replace "yourApiKey" with your API token!

Adding a group

Request Parameters:

Parameter	Description
group	(required) name of a new group

Response Parameters:

Parameter	Description
id	new group ID

groupDelete

Request example:

{
    "token": "yourApiKey",
    "method":"groupAdd",
    "groupId":73
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Deleting a group

Request Parameters:

Parameter	Description
groupId	(required) group ID

groupUpdate

Request example:

{
    "token": "yourApiKey",
    "method":"groupAdd",
    "groupId":73,
    "groupName":"New group name"
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Updating the group name

Request Parameters:

Parameter	Description
groupId	(required) group ID
groupName	(required) group new name

limits

Request example:

{
    "token": "yourApiKey",
    "method":"limits"
}

Response example:

{
    "limits": {
        "project": {
            "value": 10000000,
            "title": "Projects",
            "currentValue": 99
        }
    },
    "projectLimits": {
        "search_engine": {
            "value": 20,
            "title": "Search engines/project",
            "projectValues": {
                "2": 2,
                ...
            }
        },
        "keyword": {
            "value": 10000000,
            "title": "Keywords/project",
            "projectValues": {
                "2": 250,
                ...
            }
        },
        ...

Make sure you replace "yourApiKey" with your API token!

List of all user limits

Response Parameters:

Parameter	Description
limits	common limits array
limits.project	“project” limit alias, it’s data in the array, where value is the limit value, currentValue is the current value for this limit
projectLimits	projects limits array. In this array limits aliases are the keys. Value is the limit value, title - it’s title, projectValues is the current limit values for each project (for example, keyword.projectValues: {"2": 1663} means that project with ID=2 contains 250 keywords right now

limit

Request example:

{
    "token": "yourApiKey",
    "method":"limit",
    "limit":"project",
    "project_id":7
}

Response example:

{
     "limit": 100,
     "currentValue": 99
 }

Make sure you replace "yourApiKey" with your API token!

Data for each limit

Request Parameters:

Parameter	Description
limit	(required) limit alias
project_id	if specified, then the limit values for chosen project are displayed

Response Parameters:

Parameter	Description
limit	user limit value
currentValue	current value for chosen project

sharedProjects

Request example:

{
    "token": "yourApiKey",
    "method":"sharedProjects"
}

Response example:

[
    {
        "id": 18,
        "name": "Some Project"
    },
    ...
]

Make sure you replace "yourApiKey" with your API token!

List of all projects shared for user

Response Parameters:

Parameter	Description
id	ID of the shared project
name	name of the shared project

Project Statistic

statistic

Request example:

{
    "token": "yourApiKey",
    "method":"statistic",
    "project_id": 7,
    "domain": 5,
    "withLinks":1,
    "withAnchors":1,
    "withSnippets":1
}

Response example:

{
    "7330": [                                   // report data from id = 7330
        {
            "domain": "lenta.ru",
            "domain_id": 5,
            "data": [                           // domain data for lenta.ru
                {
                    "category": "Main",
                    "category_id": 490,
                    "data": [                   // Data from Main category
                        {
                            "keyword": "lenta",
                            "key_id": 78619,
                            "data": {           // data for the keyword "lenta"
                                 "858": [       // search engine data
                                    1,          // position
                                    "https://lenta.ru/", // Link for the position
                                    "«<b>Lenta</b>.ru» — internet-gazette - <b>Moscow</b>", // Anchor
                                    "some text about something, <wbr/>another additional text <wbr/>Фотогалерея.<b>", // Snippet
                                    1           // Does it possible to check position
                                ],
                                ...
                            },
                        },
                        ...
                    ],
                },
                ...
            ],
        },
    ],
    ...
}

Make sure you replace "yourApiKey" with your API token!

Returns the data array of the project statistic

Request Parameters:

Parameter	Description
project_id	(required) Project ID
domain	(required) Domain ID
se	ID SE or 0 if all. (By default - all search engines)
show	KWs flag with or without positions ('position')
start_date	Timestamp of the beginning of the interval in which the reports should be located, which should be selected for building the statistics array
end_date	Timestamp of the end of the interval in which the reports should be located, which are selected for building the statistics array
schedules	Line ID of reports separated by comma - if the parameter is specified, only these reports will be selected. If not - the latest reports are displayed
category	category ID or -1 if all. (By default - all the SE)
search	Search string by COP name
page	for pagination by reports (default - 0)
top	keywords sampling only with positions above the specified value. Possible options - 3, 10, 30, 'all' (by default - 'all')
sort	Flag for sorting keywords by certain values (by default - sorting by keyword name). Possible options - 1(A-Z - sorting by CW name), 2(1-100 - sorting by keyword highest position, from highest to lowest), 3(100-1 - sorting by keyword highest position, from lowest to highest)
withcat	display the keywords with or without categories (0)
keyPage	Page for keywords pagination - only works when only one domain is selected in the settings
withLinks	Flag for displaying links in the statistics array
withAnchors	Flag for displaying anchors in the statistics array
withSnippets	Flag for displaying snippets in the statistics array
externalDomain	ID for outputting statistics on a domain that is not included in the list of project domains

Response Parameters:

Отдается массив данных с ключами - id выбранных отчетов. Каждый массив одного отчета, разбитый на домены, дальше - на категории, категории разбиваются на ключевые слова, а ключевые слова - на ПС, для которых выводится массив значений - позиция, ссылка, анкор, сниппет и флаг состояния просмотра выдачи ПС

Project - Keywords

projectKeywords

Request example:

{
    "token": "yourApiKey",
    "method":"projectKeywords",
    "project_id":7,
    "withColumns":1,
    "category_id":1
}

Response example:

{
    "items": [
        {
            "key_id": 2046015,
            "key": "some keyword",
            "category_id": 1,
            "columnData": {
                "2": {
                    "1": "https://www.google.com/maps/d/viewer?usp=sharing&mid=1gkXz6JI-kyeMa7ZHGlKBB4mIu9w",
                    "5": "",
                    "253": "https://www.youtube.com/playlist?list=PLC7_RzojUnJcKwuiOSyjNvuB9WkQrGlEl",
                    "1983720": ""
                },
                "25": "some value"
            }
        },
        ...
    ],
    "totalCount": 3,
    "page": 1
}

Make sure you replace "yourApiKey" with your API token!

Returns the project keywords

Request Parameters:

Parameter	Description
project_id	(required) ID
page	by Default 0
pageSize	by default 20. No more than 300
withColumns	by default 0, if 1 - will be given to the KW with the values of all columns
category_id	if specified - will be given only to the KW, which belong to the specified category, can be passed a number or array of numbers
key_ids	if specified - will be given to the KW with id, which are in this array (search for KW id)
search	search the keyword by name

Response Parameters:

Parameter	Description
items	keywords array. It contains the next: key_id - KW id, key - KW, category_id - category, to which KW belongs, columnData - (optional) the data columns for this KW. In the columnData array, the columnData keys are the column id, and the elements themselves are the column values for this KW. If the column id = 2 (column is relevant to the URL), the value will be an array, where the keys are the domain id, and the elements - the relevant links.
totalCount	is the total number of KWs for the received settings.
page	Current page

projectKeywordsAdd

Request example:

{
    "token": "yourApiKey",
    "method":"projectKeywordsAdd",
    "project_id":7,
    "category_id":1,
    "keywords":[
        "New keyword",
        "One more new keyword"
    ]
}

Response example:

{
    "success": true,
    "added": 2,
    "ids": [
        2048334,
        2048335
    ],
    "exist": []
}

Make sure you replace "yourApiKey" with your API token!

Add the keyword to the project

Request Parameters:

Parameter	Description
project_id	(required) ID
keywords	(required) array of added KWs in the form of an array of strings, not more than 1000 KWs in the array
category_id	If specified, all KWs are stored in the selected category, if not - in the default category
skipFailed	If 1 is specified, they will be skipped and no error will be displayed when the CW array contains erroneous names. By default - the error is displayed

Response Parameters:

Parameter	Description
added	number of added KWs
ids	ID’s of the added KWs
exist	an array of existing KWs in the project (if there are KWs in the list of added ones that already exist in the project)

projectKeywordsDelete

Request example:

{
    "token": "yourApiKey",
    "method":"projectKeywordsDelete",
    "project_id":7,
    "keyword_ids":[
        2048334,
        2048335
    ]
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Delete the keywords in the project

Request Parameters:

Parameter	Description
project_id	(required) ID
keyword_ids	(required) array of the IDs of the KWs for deletion

projectKeywordsChangeCategory

Request example:

{
    "token": "yourApiKey",
    "method":"projectKeywordsChangeCategory",
    "project_id":241,
    "keyword_ids":[
        2046015
    ],
    "category_id": 298
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Change the keyword category

Request Parameters:

Parameter	Description
project_id	(required) ID
category_id	(required) Category ID
keyword_ids	(required) KWs array - key_id from CW using projectKeywords method

projectKeywordsColumnsEdit

Request example:

{
    "token": "yourApiKey",
    "method":"projectKeywordsColumnsEdit",
    "project_id":241,
    "keywords":[
        {
            "keyword_id":80509,
            "column_id":25,
            "value":123
        },
                {
            "keyword_id":2046015,
            "column_id":2,
            "domain_id":4,
            "value":"http://yandex.ru/testPage"
        }
    ]
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Change the data in the keywords columns

Request Parameters:

Parameter	Description
project_id	(required) ID
keywords	(required) KWs array with column values. The presence of fields 'column_id', 'keyword_id', 'value' is required; if the column relevant to the url changes, the domain_id field is also required

projectKeywordsRename

Request example:

{
    "token": "yourApiKey",
    "method":"projectKeywordsRename",
    "project_id":7,
    "keywords":[
        {
            "key_id":2046015,
            "keyword":"New keyword"
        }
    ]
}

Response example:

{
    "success": true,
    "renamed": {
        "New keyword": 2048336
    }
}

Make sure you replace "yourApiKey" with your API token!

Change the project’s keywords names

Request Parameters:

Parameter	Description
project_id	(required) ID
keywords	(required) KWs array for renaming - it must contain key_id and keyword keys (new KW name)

Response Parameters:

Parameter	Description
renamed	array of renamed KWs, where the key is the new KW name and the element is its id

projectKeywordsDeleteAll

Request example:

{
    "token": "yourApiKey",
    "method":"projectKeywordsDeleteAll"
}

Response example:

{
    "success": true,
}

Make sure you replace "yourApiKey" with your API token!

Request Parameters:

Parameter	Description
project_id	(required) ID

projectKeywordsPick

Request example:

{
    "token": "yourApiKey",
    "method":"projectKeywordsPick",
    "project_id": 7,
    "key":"283",
    "schedule_id":7267,
    "se":39
}

Response example:

[
    "http://korrespondent.net/",
    "http://news.bigmir.net/",
    "https://www.obozrevatel.com/",
    ...

Make sure you replace "yourApiKey" with your API token!

Gives the list of all links received for the keyword, search engine and project

Request Parameters:

Parameter	Description
project_id	(required) ID
key	(required) ID of the keyword
schedule_id	(required) report ID
se	(required) ID of the project search engine

Project - Domains

projectDomains

Request example:

{
    "token": "yourApiKey",
    "method":"projectDomains",
    "project_id":7,
    "type":1
}

Response example:

{
    "items": [
        {
            "rel_id": 1501,
            "domain_id": 5,
            "is_own": 1,
            "domain": "lenta.ru"
        },
        ...
    ],
    "totalCount": 2,
    "page": 0
}

Make sure you replace "yourApiKey" with your API token!

List of all domains

Request Parameters:

Parameter	Description
project_id	(required) ID
page	default 0
pageSize	20 by default. Not more than 100
type	(if not specified, all domains are given) - filter by domain type - your own domain (1) or competing domain (0)

Response Parameters:

Parameter	Description
items	array of domains. In it: domain_id - domain id, rel_id - domain-project communication id, is_own - domain type (1 - own domain, 0 - competitor domain), domain - domain name
totalCount	total number of domains by the received settings
page	Current page

projectDomainsAdd

Request example:

{
    "token": "yourApiKey",
    "method":"projectDomainsAdd",
    "project_id":7,
    "domains": [
        {
            "domain":"yandex.ru",
            "is_own":1
        }
    ]
}

Response example:

{
    "success": true,
    "added": {
        "yandex.ru": 1983720
    }
}

Make sure you replace "yourApiKey" with your API token!

Add project domains

Request Parameters:

Parameter	Description
project_id	(required) ID
domains	(required) array of domains to add. For each element of the array, the following fields must be specified: domain - the name of the added domain, is_own - its own domain (1) or competing domain (0)

Response Parameters:

Parameter	Description
added	array of added domains, where the key is the added domain, and the element is its id

projectDomainsDelete

Request example:

{
    "token": "yourApiKey",
    "method":"projectDomainsDelete",
    "project_id":7,
    "domain_ids": [
        1983720
    ]
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Delete project domains

Request Parameters:

Parameter	Description
project_id	(required) ID
domain_ids	(required) array of domains to be removed

projectDomainsChangeType

Request example:

{
    "token": "yourApiKey",
    "method":"projectDomainsChangeType",
    "project_id":7,
    "domain_ids":[
        5
    ],
    "type":1
}

Response example:

{
    "success": true,
    "changed_domains": {
        "5": 1
    }
}

Make sure you replace "yourApiKey" with your API token!

Change domain type

Request Parameters:

Parameter	Description
project_id	(required) ID
domain_ids	(required) Domains IDs array
type	if specified, this type is set for all domains

Response Parameters:

Parameter	Description
changed_domains	array of processed domains, where the key is the domain id, and the value is the current type (1 — own domain, 0 — competitor domain)

projectDomainsCollect

Request example:

{
    "token": "yourApiKey",
    "method":"projectDomainsCollect",
    "project_id":7
}

Response example:

[
    "vk.com",
    "yandex.ru",
    "ok.ru",
    "24tv.ua",
    "news.yandex.ru",
    "ru.wikipedia.org",
    "korrespondent.net",
    "books.google.com",
    ...

Make sure you replace "yourApiKey" with your API token!

Returns 30 most common domains from statistics

Request Parameters:

Parameter	Description
project_id	(required) ID

Project - Search engines

projectSearchEngines

Request example:

{
    "token": "yourApiKey",
    "method":"projectSearchEngines",
    "project_id":7
}

Response example:

{
    "16": {
        "short": "G1",
        "name": "Google",
        "settings": "(www.google.com, Dutch, English, Russia)",
        "settingsArray": {
            "google_domains": {
                "display": "www.google.com",
                "value": "www.google.com",
                "id": 1
            },
            ...
        },
        "se_id": 1
    },
    ...

Make sure you replace "yourApiKey" with your API token!

Getting all active PS project

Request Parameters:

Parameter	Description
project_id	(required) ID

Response Parameters:

An array is offered, where the keys are the id of the PS project. In each array: short is the abbreviated name of the PS, name is the name of the PS, settings is the set of the current settings by the line, settingsArray is the array of the current values ​​of the settings of the PS, se_id is the global search engine id in SpySERP

projectSearchEngine

Request example:

{
    "token": "yourApiKey",
    "method":"projectSearchEngines",
    "project_id":7,
    "project_se_id":16
}

Response example:

{
    "short": "G1",
    "name": "Google",
    "settings": "(---Seattle)",
    "settingsArray": {
        "google_regions": {
            "display": "---Seattle",
            "value": "16",
            "id": 592
        }
    },
    "project_se_id": 3
}

Make sure you replace "yourApiKey" with your API token!

Receiving SE project by its ID

Request Parameters:

Parameter	Description
project_id	(required) ID
project_se_id	(required) ID of the SE project

Response Parameters:

Parameter	Description
short	abbreviation of the search engine
name	name of the search engine
settings	set of current settings by line
settingsArray	array of current values ​​of SE settings
se_id	global search engine id in SpySERP

projectSearchEnginesAdd

Request example:

{
    "token": "yourApiKey",
    "method":"projectSearchEnginesAdd",
    "project_id": 7,
    "engines":[
        {
            "se_id":1,
            "settings":{
                "google_langs":"lang_ru",
                    "google_location":"",
                    "google_domains":"www.google.com",
                    "google_hl":"en",
                    "google_country_codes":"RU"
            }
        }
    ]
}

Response example:

{
    "success": true,
    "added": [
        855
    ]
}

Make sure you replace "yourApiKey" with your API token!

Add search engine to the project

Request Parameters:

Parameter	Description
project_id	(required) ID
engines	array of the added PS, in each element of the array there should be a se_id element ID of the SE being added, and settings - an array of settings (for example "google_langs": "lang_en").

Response Parameters:

Parameter	Description
added	array of the search engine added IDs

projectSearchEnginesEdit

Request example:

{
    "token": "yourApiKey",
    "method":"projectSearchEnginesEdit",
    "project_id": 7,
    "engine_id":803,
    "settings":{
            "google_langs":"lang_ru",
                "google_location":"",
                "google_domains":"www.google.ru",
                "google_hl":"en",
                "google_country_codes":"RU"
        }
}

Response example:

{
    "success": true,
}

Make sure you replace "yourApiKey" with your API token!

Add search engine to the project

Request Parameters:

Parameter	Description
project_id	(required) ID
engine_id	(required) Engine ID
settings	(required) array of all new SE settings

projectSearchEnginesDelete

Request example:

{
    "token": "yourApiKey",
    "method":"projectSearchEnginesDelete",
    "project_id": 7,
    "relation_id": 855
}

Response example:

{
    "success": true,
}

Make sure you replace "yourApiKey" with your API token!

Delete the SE from the project

Request Parameters:

Parameter	Description
project_id	(required) ID
relation_id	(required) id of SE of the project that is being deleted

Project - Categories

projectCategories

List of the project categories

Request example:

{
    "token": "yourApiKey",
    "method":"projectCategories",
    "project_id":7
}

Response example:

{
    "items": [
        {
            "id": 490,
            "title": "Main",
            "keysCount": 8,
            "default": 1,
            "keyPagesCount": 1
        },
        ...
    ],
    "totalCount": 2,
    "page": 0
}

Make sure you replace "yourApiKey" with your API token!

Request Parameters:

Parameter	Description
project_id	(required) ID
page	Page
pageSize	Page size. Not more than 100

Response Parameters:

Parameter	Description
items
items.id	category ID
items.title	category name
items.keysCount	number of keywords in this category
items.default	whether this category is the default category (1 - yes, 0 - no)
totalCount	total number of categories
page	current page

projectCategoriesAdd

Request example:

{
    "token": "yourApiKey",
    "method":"projectCategoriesAdd",
    "project_id":7,
    "categories":[
        "New category"
    ]
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Adding categories to the project

Request Parameters:

Parameter	Description
project_id	(required) ID
categories	(required) array of new category names

projectCategoriesDelete

Request example:

{
    "token": "yourApiKey",
    "method":"projectCategoriesDelete",
    "project_id":7,
    "category_ids":[
        486
    ]
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Deleting a project category

Request Parameters:

Parameter	Description
project_id	(required) ID
category_ids	(required) array id categories for deletion

projectCategoriesEdit

Request example:

{
    "token": "yourApiKey",
    "method":"projectCategoriesEdit",
    "project_id": 7,
    "category_id": 190,
    "category": "Edited second test category"
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Editing the project category name

Request Parameters:

Parameter	Description
* project_id	(required) ID
* category_id	(required) ID of the category being edited
* category	(required) new category name
* default_category	1 or 0

Project - Columns

projectColumns

Request example:

{
    "token": "yourApiKey",
    "method":"projectColumns",
    "project_id":7,
    "withFilled":1
}

Response example:

{
    "items": [
        {
            "id": 245,
            "type_id": 0,
            "description": "Some column",
            "hide": false,
            "region": false,
            "freq_type": false,
            "conformity": false,
            "deleted": false,
            "column_type": "common",
            "filled": 0
        },
        ...
        ],
    "totalCount": 2,
    "page": 0
}

Make sure you replace "yourApiKey" with your API token!

List of all project columns

Request Parameters:

Parameter	Description
project_id	(required) ID
page	0 by default
pageSize	20 by default. Not more than 100
withFilled	additionally returns for each column a field filled with the number of filled column values for all project keywords

Response Parameters:

items | Array of project columns. In each array: id - column ID, type_id - column type (0 - number, 1 - row. Used when sorting statistics by column), description - column name, hide - flag, whether the column is hidden on the statistics page, region - id region, if column is Yandex frequency, freq_type - 1, if frequency column, conformity - type of compliance, if Yandex frequency column, deleted - flag, whether column is deleted, column_type - column type, filled - (optional) number of keywords from filled values for this column totalCount | total columns page page | current page

projectColumnsAdd

Request example:

{
    "token": "yourApiKey",
    "method":"projectColumnsAdd",
    "project_id":7,
    "column": {
        "description": "Some column",
        "type_id":0
    }
}

Response example:

{
    "success": true,
    "columnId": 245
}

Make sure you replace "yourApiKey" with your API token!

Adding a column to the project

Request Parameters:

Parameter	Description
project_id	(required) ID
column	(required) If a number is passed in the field, then a column with the given ID among the available columns to be added is searched for - get separately by the projectColumnsAvailable method. If an array is transferred to the field, a new column is added, filled with parameters from the array. In this case, mandatory elements of the array are 'description', 'type_id' (column type. 0 - numeric, 1 - lowercase)

Response Parameters:

Parameter	Description
columnId	id of the column being added

projectColumnsAvailable

Request example:

{
    "token": "yourApiKey",
    "method":"projectColumnsAvailable",
    "project_id":7
}

Response example:

[
    {
        "id": 2,
        "description": "Relevant URL",
        "type": "Inbuilt column"
    },
    {
        "id": 169,
        "description": "ewrewrewrew ewr er ewrewrewrewrewrewrewr",
        "type": "Own column"
    },
    ...

Make sure you replace "yourApiKey" with your API token!

List of all project columns available for adding (built-in columns, or those columns that exist in other user projects)

Request Parameters:

Parameter	Description
project_id	(required) ID

Response Parameters:

Array of existing columns to add.

Parameter	Description
description	Column description
type	column type ("Inbuilt column" is a built-in column that can be added by any user, "Own column" is a column that exists in one of the other user projects)

projectColumnsDelete

Request example:

{
    "token": "yourApiKey",
    "method":"projectColumnsDelete",
    "project_id":7,
    "column_id":2
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Delete columns from the project

Request Parameters:

Parameter	Description
project_id	(required) ID
column_id	(required) id of the column being deleted

projectColumnsEdit

Request example:

{
    "token": "yourApiKey",
    "method":"projectColumnsEdit",
    "project_id":7,
    "column_id":25,
    "column": {
        "description": "Some column",
        "type_id":0
    }
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Editing a personal column (you cannot edit the column of a relevant URL or frequency)

Request Parameters:

Parameter	Description
project_id	(required) ID
column_id	(required) Column ID
column	(required) an array is passed to the field. The required elements of the array are 'description', 'type_id' (column type. 0 - numeric, 1 - lowercase)

projectColumnsHide

Request example:

{
    "token": "yourApiKey",
    "method":"projectColumnsHide",
    "project_id":7,
    "column_id":78
}

Response example:

{
    "success": true,
    "hide": true
}

Make sure you replace "yourApiKey" with your API token!

Hiding a column on the statistics page. Returns hide - current value is true / false

Request Parameters:

Parameter	Description
project_id	(required) ID
column_id	(required) Column Id

Response Parameters:

Возвращает hide - current value is true / false

projectColumnsAutocollect

Request example:

{
    "token": "yourApiKey",
    "method":"projectColumnsAutocollect",
    "project_id":7,
    "column_id":78
}

Response example:

{
    "success": true,
    "msg": "Task added successfully"
}

Make sure you replace "yourApiKey" with your API token!

Automatic collection of links for the column relevant url from existing statistics, or automatic start of tasks for collecting values for frequency columns (if the transferred column_id belongs to the frequency column)

Request Parameters:

Parameter	Description
project_id	(required) ID
column_id	(required) Column ID

Project - Frequencies

projectFrequencyYandexRun

Request example:

{
    "token": "yourApiKey",
    "method":"projectFrequencyYandexRun",
    "project_id": 7,
    "conformities":["Freq"],
    "category":-1
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Starting frequency collection

Request Parameters:

Parameter	Description
project_id	(required) ID
conformities	(required) Yandex compliance array id
category	(required) category id, if you need to collect frequencies only for the CS from a certain category, if -1 - then for all categories
skipExist	flag - whether to skip existing frequency values or not
regions	id array of Yandex regions

projectFrequencyColumns

Request example:

{
    "token": "yourApiKey",
    "method":"projectFrequencyColumns",
    "project_id": 7
}

Response example:

{
    "existFrequencies": {
        "109": {
            "freq_type": 1,
            "conformity": "Freq",
            "region": "213",
            "queriesDoneCount": 17,
            "columnId": 109,
            "category": "-1",
            "timeStart": 1498910291,
            "skipOnExist": true,
            "hide": true,
            "description": "Frequency Yandex (---Moskow, Freq)",
            "existsCount": 0
        }
    },
    "keywordsCount": "45"
}

Make sure you replace "yourApiKey" with your API token!

Getting a list of frequency columns with additional parameters

Request Parameters:

Parameter	Description
project_id	(required) ID

Response Parameters:

Parameter	Description
existFrequencies	array of frequency columns. In this array, the keys of the elements are id columns, and the value is an array with the following components: freq_type is the frequency type (1 is Yandex frequency), conformity is the match type for Yandex, region is the region id for Yandex, queriesDoneCount is the number of keywords requested for the last task for this column, category - if -1, then the frequency of the last successfully completed task was taken for all keywords, and if a number is indicated, then only for the category with id = category, timeStart is the beginning of frequency collection, skipOnExist - task flag, if 1 - then, when collecting, the existing values of frequency were skipped ti, hide - whether or not the column is hidden on the statistics page, description - the column description, existsCount - the number of keywords for which the column values are collected.
keywordsCount	number of keywords in the project

projectFrequencyYandexRegions

Request example:

{
    "token": "yourApiKey",
    "method":"projectFrequencyYandexRegions",
    "project_id": 21
}

Response example:

{
    "1": "--Moskow region",
    "217": "---Pushino",
    "10716": "---Balashykha"
}

Make sure you replace "yourApiKey" with your API token!

Getting a list of Yandex project regions

Request Parameters:

Parameter	Description
project_id	(required) ID

Response Parameters:

An array of Yandex regions is presented for a project where the key is the region id and the value is its name

projectFrequencyYandexRegionsDelete

Request example:

{
    "token": "yourApiKey",
    "method":"projectFrequencyYandexRegionsDelete",
    "project_id": 21,
    "region_id":217
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Removing a Yandex region from the list of project regions

Request Parameters:

Parameter	Description
project_id	(required) ID
region_id	(required) ID of the region being deleted

projectFrequencyYandexRegionsAdd

Request example:

{
    "token": "yourApiKey",
    "method":"projectFrequencyYandexRegionsAdd",
    "project_id": 7,
    "region_id":10741
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Adding a Yandex region to the list of project regions

Request Parameters:

Parameter	Description
project_id	(required) ID
region_id	(required) Region ID

projectFrequencyTasks

Request example:

{
    "token": "yourApiKey",
    "method":"projectFrequencyTasks",
    "project_id": 7
}

Response example:

[
    "items": [
        {
                "id": 1046,
                "time_created": 1508242196,
                "time_completed": 1508242203,
                "status": 4,
                "progress": 100,
                "task_config": {
                    "region": "10719",
                    "category": "-1",
                    "columnId": 114,
                    "freq_type": "1",
                    "conformity": "Freq",
                    "skipOnExist": false
                }
            },
          ...
    ],
    "totalCount": 2,
    "page": 0
}

Make sure you replace "yourApiKey" with your API token!

List of frequency collection tasks for speakers. Sorted from new to old

Request Parameters:

Parameter	Description
project_id	(required) ID
page	Page
pageSize	Page Size. Not more than 100

Response Parameters:

Parameter	Description
items	array of tasks in which: id - task ID, time_created - task start timestamp, time_completed - task start timestamp, status - status (4 - completed successfully), progress - collection progress in percent, task_config - task settings, where: region - Yandex region id, category category id - or -1 if for all categories, columnId - id columns for which values are collected, freq_type - frequency type (1 - Yandex), conformity - Yandex frequency frequency type, skipOnExist - whether to skip charge for cop and column if value already exists
totalCount	total number of items
page	Current page

projectFrequencyTable

Request example:

{
    "token": "yourApiKey",
    "method":"projectFrequencyTable",
    "project_id": 7
}

Response example:

[
    "items": {
            "982": {
                "78": 0,
                "80": 0,
                "82": 0,
                "84": 0,
                "109": "15",
                "110": 13,
                "111": 13,
                "112": 6,
                "113": 6,
                "120": 0
            },
          ...
    ],
    "totalCount": 120,
    "page": 0
}

Make sure you replace "yourApiKey" with your API token!

Frequency columns data for all project COPs

Request Parameters:

Parameter	Description
project_id	(required) ID
page	Page
pageSize	Page Size. Not more than 100
sc	A sort view. Default = sc = 'key', if you specify the column id - sorting will be carried out according to the values ​​of the selected column
sort_type	Sort order - asc or desc
category	category ID - if the parameter is specified, only data for the CS will be displayed that relates to the specified category

Response Parameters:

Parameter	Description
items	array of the keywords, where the key is the ID of the keyword and, in the value, an array of values of the frequency columns (column id => value)
totalCount	total number of items
page	Current page

Project - open access

projectSharedEmails

Request example:

{
    "token": "yourApiKey",
    "method":"projectSharedEmails",
    "project_id": 7
}

Response example:

{
    "8": "test@test.com"
}

Make sure you replace "yourApiKey" with your API token!

Getting a list of emails for which the project is open

Request Parameters:

Parameter	Description
project_id	(required) ID

Response Parameters:

Returns the array, where the keys are the user's id, and the elements are its email

projectSharedUrlCreate

Request example:

{
    "token": "yourApiKey",
    "method":"projectSharedUrlCreate",
    "project_id": 7
}

Response example:

{
    "success": true,
    "publicUrl": "http://spyserp.com/share?id=228acc8d060e8f7faa4de05bd93eb2ca"
}

Make sure you replace "yourApiKey" with your API token!

Opening access to the project for unregistered users by reference - the link is returned in the response. This method re-creates and saves the link

Request Parameters:

Parameter	Description
project_id	(required) ID

Response Parameters:

Parameter	Description
publicUrl	link for public access to the project

projectSharedUrlGet

Request example:

{
    "token": "yourApiKey",
    "method":"projectSharedUrlGet",
    "project_id": 7
}

Response example:

{
    "publicUrl": "http://spyserp.com/share?id=228acc8d060e8f7faa4de05bd93eb2ca"
}

Make sure you replace "yourApiKey" with your API token!

Getting a link to a publicly accessible project

Request Parameters:

Parameter	Description
project_id	(required) ID

Response Parameters:

Parameter	Description
publicUrl	link for public access to the project

projectSharedUser

Request example:

{
    "token": "yourApiKey",
    "method":"projectSharedUser",
    "project_id": 7,
    "email":"test@spyserp.com"
}

Response example:

{
    "success": true,
    "users": {
        "5": "test@spyserp.com",
        "8": "test@test.com"
    }
}

Make sure you replace "yourApiKey" with your API token!

Opening access to the project for an individual user by email

Request Parameters:

Parameter	Description
project_id	(required) ID
email	(required) Email

Response Parameters:

Parameter	Description
users	an array of all users for whom the project is currently open to access

projectSharedUserDelete

Request example:

{
    "token": "yourApiKey",
    "method":"projectSharedUserDelete",
    "project_id": 7,
    "user_id":5
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Remove user from the list for which access to the project is open

Request Parameters:

Parameter	Description
project_id	(required) ID
user_id	(required) User ID

Project - Other Methods

projectSchedules

Request example:

{
    "token": "yourApiKey",
    "method":"projectSchedules",
    "project_id":7
}

Response example:

{
    "items": [
        {
            "id": 245,
            "type_id": 0,
            "description": "Some column",
            "hide": false,
            "region": false,
            "freq_type": false,
            "conformity": false,
            "deleted": false,
            "column_type": "common",
            "filled": 0
        },
        ...
    ],
    "totalCount": 2,
    "page": 0
}

Make sure you replace "yourApiKey" with your API token!

List of project reports. From new to old

Request Parameters:

Parameter	Description
project_id	(required) ID
page	0 by default
pageSize	20 by default. Not more than 100

Response Parameters:

Parameter	Description
items	array of reports. time_created - timestamp of report creation, time_started- timestamp of report launch, time_completed - timestamp of report parsing completed, time_parse - array with report parsing time, status - report status (4 - completed successfully), type - report launch type - manually or automatically , progress is the indicator of report completion in percent, data is a snapshot of report statistics, parseData is the number of parsed KSs.
totalCount	total number of columns
page	current page

projectSchedule

Request example:

{
    "token": "yourApiKey",
    "method":"projectSchedule",
    "project_id":7,
    "schedule_id":6975
}

Response example:

{
    "id": 6926,
    "time_created": 1508740200,
    "time_started": 1508740201,
    "time_completed": 1508741392,
    "time_parse": {
        "parsing": 1189,
        "saving": 2.0652
    },
    "status": 4,
    "type": 1,
    "progress": 100,
    "data": {
        "up": {
            "253": 50
        },
        ...
    },
}

Make sure you replace "yourApiKey" with your API token!

Data of the exact project report

Request Parameters:

Parameter	Description
project_id	(required) ID

Response Parameters:

Parameter	Description
id	ID отчета
time_created	report creation timestamp,
time_started	report launch timestamp,
time_completed	report parsing completion timestamp,
time_parse	array with report parsing time,
status	report status (4 completed successfully),
type	type of report start - manually or automatically,
progress	report completion rate in percent,
data	snapshot of report statistics,
parseData	quantities parsed by the keywords.

projectActiveSchedule

Request example:

{
    "token": "yourApiKey",
    "method":"projectActiveSchedule",
    "project_id":7
}

Response example:

{
    "id": 6990,
    "time_created": 1508942051,
    "progress": 0
}

Make sure you replace "yourApiKey" with your API token!

Getting the active report (what is being parsed at the moment)

Request Parameters:

Parameter	Description
project_id	(required) ID

Response Parameters:

Parameter	Description
id	id of the report that is being processed
time_created	report creation timestamp
progress	parsing percentage

projectActiveTasks

Request example:

{
    "token": "yourApiKey",
    "method":"projectActiveTasks",
    "project_id":7
}

Response example:

[
    {
        "id": 1748,
        "time_created": 1508942611,
        "progress": 0,
        "task_config": {
            "region": "213",
            "category": -1,
            "columnId": 112,
            "freq_type": "1",
            "conformity": "\"[Freq]\"",
            "skipOnExist": true
        }
    },

Make sure you replace "yourApiKey" with your API token!

Getting active tasks (for frequencies)

Request Parameters:

Parameter	Description
project_id	(required) ID

Response Parameters:

Parameter	Description
id	ID of the report that is being processed
time_created	report creation timestamp
progress	parsing percentage
task_config	settings task before launch

projectSaveSetting

Request example:

{
    "token": "yourApiKey",
    "method":"projectSaveSetting",
    "project_id": 21,
    "setting":"parseAnchor",
    "value":0
}

Response example:

{
    "success": true
}

Make sure you replace "yourApiKey" with your API token!

Save individual project settings

Request Parameters:

Parameter	Description
project_id	(required) ID
setting	(required) alias settings
value	(required) new setting value

Errors

The Kittn API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.