SEO-проекты · token

`groups` Группы запросов проекта

Группа groups управляет группами поисковых запросов проекта: отдаёт их список, создаёт группу (сразу с новыми запросами), удаляет группы и переносит запросы из одной группы в другую. Изменения — те же, что на странице «Управление запросами» в интерфейсе, с теми же проверками. Лимиты не тратятся.

Адрес: /projects/api/v1/groups/<метод>
Доступ: get — любой доступ к проекту; add, delete, move — владелец или доступ на запись
Лимиты: не тратит

Список групп

GET /projects/api/v1/groups/get

Группы проекта и системная группа «Общая» (id 1). Отдаётся массивом без обёртки status/result.

Тип группы метод не фильтрует, поэтому в списке могут оказаться и группы URL проекта. Класть в них поисковые запросы нельзя: add, delete и move такие группы не примут.

Параметры query

token string обязательный

Ключ API из настроек аккаунта — тот же, что key у методов инструментов.
project_id int обязательный

ID проекта. Виден в адресе страницы проекта и в ответе projects/get.

Ответ

[].id string

ID группы.
[].name string

Название группы.

GET /projects/api/v1/groups/get

curl -G 'https://tools.pixelplus.ru/projects/api/v1/groups/get' \
  --data-urlencode 'token=ВАШ_КЛЮЧ' \
  --data-urlencode 'project_id=7002'

<?php
$url = 'https://tools.pixelplus.ru/projects/api/v1/groups/get?' . http_build_query([
    'token' => 'ВАШ_КЛЮЧ',
    'project_id' => 7002,
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.get(
    "https://tools.pixelplus.ru/projects/api/v1/groups/get",
    params={
        "token": "ВАШ_КЛЮЧ",
        "project_id": 7002,
    },
    timeout=60,
)
print(response.json())

project_id обязательный ID проекта. Виден в адресе страницы проекта и в ответе projects/get

Запрос настоящий — выполнится с вашим ключом

Пример ответа

[
    {
        "id": "1",
        "name": "Общая"
    },
    {
        "id": "22150",
        "name": "Брендовые"
    },
    {
        "id": "22151",
        "name": "Коммерческие"
    }
]

Создать группу

POST /projects/api/v1/groups/add

Создаёт группу и, если переданы queries, добавляет в неё новые запросы. Если группа с таким названием в проекте уже есть (или это «Общая»), новая не создаётся — запросы добавятся в существующую. Больше 50 запросов добавляются в фоне: ответ приходит сразу, по завершении придёт уведомление.

Число запросов в проекте ограничено так же, как в интерфейсе. Если новые запросы не помещаются, ни один не добавляется и придёт ошибка 52, но сама группа при этом уже создана.

Параметры query и JSON-тело

token string обязательный

Ключ API владельца проекта или пользователя с доступом на запись. Промо- и тестовый ключи не принимаются.
project_id int обязательный

ID проекта. Виден в адресе страницы проекта и в ответе projects/get.
name string обязательный

Название группы.
order int

Сортировка группы в списке. 0 тоже даёт значение по умолчанию.

По умолчанию 100
queries array

Фразы для группы: массив или строка через |. Фразы чистятся от спецсимволов и, без keep_case, приводятся к нижнему регистру.
keep_case int

Сохранить регистр фраз.

0
привести к нижнему регистру

1
оставить как есть

По умолчанию 0

Ответ

result.message string

Готово. или сообщение о том, что добавление запущено в фоне.
result.group_id int

ID созданной или найденной группы.

POST /projects/api/v1/groups/add

curl -X POST 'https://tools.pixelplus.ru/projects/api/v1/groups/add?token=ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{
      "project_id": 7002,
      "name": "Коммерческие",
      "queries": [
          "купить диван",
          "диван недорого"
      ]
  }'

<?php
$url = 'https://tools.pixelplus.ru/projects/api/v1/groups/add?' . http_build_query([
    'token' => 'ВАШ_КЛЮЧ',
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode([
        'project_id' => 7002,
        'name' => 'Коммерческие',
        'queries' => [
            'купить диван',
            'диван недорого',
        ],
    ]),
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.post(
    "https://tools.pixelplus.ru/projects/api/v1/groups/add",
    params={
        "token": "ВАШ_КЛЮЧ",
    },
    json={
        "project_id": 7002,
        "name": "Коммерческие",
        "queries": [
            "купить диван",
            "диван недорого",
        ],
    },
    timeout=60,
)
print(response.json())

project_id обязательный ID проекта. Виден в адресе страницы проекта и в ответе projects/get name обязательный Название группы queries Фразы для группы: массив или строка через | · по одному на строку

Запрос настоящий — выполнится с вашим ключом

Пример ответа

{
    "status": "ok",
    "code": 1,
    "msg": "success",
    "result": {
        "message": "Готово.",
        "group_id": 22152
    }
}

Удалить группы

POST /projects/api/v1/groups/delete

Удаляет группы проекта. Запросы по умолчанию не теряются: они переезжают в «Общую» или в группу move_to_group_id вместе со всеми позициями и историей. Системную группу «Общая» удалить нельзя.

С with_queries=1 вместе с группами безвозвратно удаляются их запросы с историей позиций — в том числе те, что состоят ещё и в других группах. Больше 50 запросов удаляются в фоне.

Параметры query и JSON-тело

token string обязательный

Ключ API владельца проекта или пользователя с доступом на запись. Промо- и тестовый ключи не принимаются.
project_id int обязательный

ID проекта. Виден в адресе страницы проекта и в ответе projects/get.
group_ids array обязательный

ID групп из groups/get: массив или строка через запятую. Для одной группы можно передать group_id.
move_to_group_id int

Куда перенести запросы удаляемых групп. Своя группа проекта или «Общая». Не учитывается при with_queries=1.

По умолчанию 1
with_queries int

Удалить группы вместе с запросами.

0
перенести запросы

1
удалить запросы безвозвратно

По умолчанию 0

Ответ

result.message string

Что сделано; при фоновом удалении — сообщение о запуске.
result.deleted int[]

ID удалённых групп.

POST /projects/api/v1/groups/delete

curl -X POST 'https://tools.pixelplus.ru/projects/api/v1/groups/delete?token=ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{
      "project_id": 7002,
      "group_ids": [
          22150,
          22151
      ]
  }'

<?php
$url = 'https://tools.pixelplus.ru/projects/api/v1/groups/delete?' . http_build_query([
    'token' => 'ВАШ_КЛЮЧ',
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode([
        'project_id' => 7002,
        'group_ids' => [
            22150,
            22151,
        ],
    ]),
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.post(
    "https://tools.pixelplus.ru/projects/api/v1/groups/delete",
    params={
        "token": "ВАШ_КЛЮЧ",
    },
    json={
        "project_id": 7002,
        "group_ids": [
            22150,
            22151,
        ],
    },
    timeout=60,
)
print(response.json())

project_id обязательный ID проекта. Виден в адресе страницы проекта и в ответе projects/get group_ids обязательный ID групп из groups/get: массив или строка через запятую · по одному на строку

Запрос настоящий — выполнится с вашим ключом

Пример ответа

{
    "status": "ok",
    "code": 1,
    "msg": "success",
    "result": {
        "message": "Группы удалены, запросы перенесены.",
        "deleted": [
            22150,
            22151
        ]
    }
}

Перенести запросы в другую группу

POST /projects/api/v1/groups/move

Убирает запросы из группы from_group_id и добавляет в группу назначения. Меняется только связь «запрос — группа»: позиции, история, продвигаемые URL и частоты привязаны к самому запросу и остаются при нём. Остальные группы запроса не затрагиваются. Перенос атомарный — при сбое ни один запрос не окажется вне обеих групп.

Параметры query и JSON-тело

token string обязательный

Ключ API владельца проекта или пользователя с доступом на запись. Промо- и тестовый ключи не принимаются.
project_id int обязательный

ID проекта. Виден в адресе страницы проекта и в ответе projects/get.
query_ids array обязательный

ID запросов проекта (из queries/get): массив или строка через запятую, до 1000. Все должны быть из этого проекта и состоять в from_group_id, иначе ничего не переносится и придёт ошибка 52 со списком лишних ID.
from_group_id int обязательный

Группа, из которой переносятся запросы.
group_id int

Группа назначения: своя группа проекта или «Общая». Нужен этот параметр или group_name.
group_name string

Название группы назначения вместо group_id: найдётся или создастся. Приоритетнее group_id.

Ответ

result.message string

Всегда Готово.
result.action string

Всегда move.
result.count int

Сколько запросов перенесено.
result.group_id int

Только с group_name: ID найденной или созданной группы.

POST /projects/api/v1/groups/move

curl -X POST 'https://tools.pixelplus.ru/projects/api/v1/groups/move?token=ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{
      "project_id": 7002,
      "query_ids": [
          8797228,
          8797229
      ],
      "from_group_id": 1,
      "group_id": 22150
  }'

<?php
$url = 'https://tools.pixelplus.ru/projects/api/v1/groups/move?' . http_build_query([
    'token' => 'ВАШ_КЛЮЧ',
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode([
        'project_id' => 7002,
        'query_ids' => [
            8797228,
            8797229,
        ],
        'from_group_id' => 1,
        'group_id' => 22150,
    ]),
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

import requests

response = requests.post(
    "https://tools.pixelplus.ru/projects/api/v1/groups/move",
    params={
        "token": "ВАШ_КЛЮЧ",
    },
    json={
        "project_id": 7002,
        "query_ids": [
            8797228,
            8797229,
        ],
        "from_group_id": 1,
        "group_id": 22150,
    },
    timeout=60,
)
print(response.json())

project_id обязательный ID проекта. Виден в адресе страницы проекта и в ответе projects/get query_ids обязательный ID запросов проекта (из queries/get): массив или строка через запятую, до 1000 · по одному на строку from_group_id обязательный Группа, из которой переносятся запросы group_id Группа назначения: своя группа проекта или «Общая»

Запрос настоящий — выполнится с вашим ключом

Пример ответа

{
    "status": "ok",
    "code": 1,
    "msg": "success",
    "result": {
        "message": "Готово.",
        "action": "move",
        "count": 2
    }
}

Ошибки

Код	Сообщение	Когда
`50`	`access error`	Ключ не передан или не найден, проекта нет, или у владельца ключа нет к нему доступа. Для `add`, `delete`, `move` — ещё и доступ только на чтение или промо-/тестовый ключ. `result` пустой.
`51`	`wrong project id`	`add`, `delete`, `move`: не передан `project_id`.
`52`	`wrong request data`	`add`, `delete`, `move`: причина — в `result.error`. Группа не найдена в проекте (в том числе попытка удалить «Общую»), пустое название, запросы не из этого проекта или не состоят в `from_group_id`, превышен лимит запросов, фоновая операция уже идёт.

Ответ с ошибкой

{
    "status": "error",
    "code": 52,
    "msg": "wrong request data",
    "result": {
        "error": "Группа запросов #1 не найдена в проекте. Список — groups/get."
    }
}

Как устроены группы

Запрос может состоять в нескольких группах сразу. Поэтому в queries/get такой запрос встречается несколько раз — по строке на группу, а в positions/get его группы перечислены через запятую.
«Общая» (id 1) — системная группа, одна на все проекты. Её нельзя переименовать или удалить, но класть в неё запросы можно. Название «Общая» в group_name, name или group у queries/set указывает на неё, дубликат не создаётся.
Запросы без единой группы в интерфейсе видны как «Без группы». В positions/get у них group_id = 0.

Формат запроса и ответа

add, delete и move принимают параметры в JSON-теле, в форме или в query-строке — в таком порядке приоритета. Списки — массивом или строкой с разделителем.

groups/get отдаёт массив без обёртки status/result — так сложилось исторически. HTTP-код всегда 200.

groups Группы запросов проекта

Список групп

Параметры query

Ответ

Создать группу

Параметры query и JSON-тело

Ответ

Удалить группы

Параметры query и JSON-тело

Ответ

Перенести запросы в другую группу

Параметры query и JSON-тело

Ответ

Ошибки

Как устроены группы

Формат запроса и ответа

`groups` Группы запросов проекта