SEO-проекты · token

`queries` Поисковые запросы проекта

Группа queries работает с поисковыми запросами проекта: отдаёт их список с группами и частотой, добавляет новые фразы (в группу и с продвигаемым URL) и удаляет запросы. Список и добавление синхронные, удаление ставится в очередь и выполняется в фоне.

Адрес: /projects/api/v1/queries/<метод>
Доступ: свои проекты и проекты с выданным доступом
Лимиты: методы не тратят; частоты новых запросов собираются так же, как при добавлении в интерфейсе

Список запросов

GET /projects/api/v1/queries/get

Запросы проекта в порядке добавления, с группой и частотой в регионе частот проекта. Отдаётся массивом без обёртки status/result.

Запрос из нескольких групп даёт по строке на каждую группу, запрос без групп — одну строку с group_id: null. offset и limit считают именно строки, а не запросы.

Параметры query

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

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

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

Сколько строк пропустить.

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

Сколько строк отдать. 0 или без параметра — 50 000.

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

Ответ

[].id string

ID запроса.
[].query string

Фраза.
[].group_id string|null

ID группы; null, если запрос ни в одной группе.
[].frequency string|null

Частота выбранного в проекте типа; null, если ещё не собрана.
[].frequency_type string

Тип частоты из настроек проекта: overall — базовая, quoted — «в кавычках», exact — «!точная», google_base — Google, custom_exact — своя точная.

GET /projects/api/v1/queries/get

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

<?php
$url = 'https://tools.pixelplus.ru/projects/api/v1/queries/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/queries/get",
    params={
        "token": "ВАШ_КЛЮЧ",
        "project_id": 7002,
    },
    timeout=60,
)
print(response.json())

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

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

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

[
    {
        "id": "8797228",
        "query": "pixeltools инструменты",
        "group_id": "1",
        "frequency": "1000",
        "frequency_type": "exact"
    },
    {
        "id": "8797229",
        "query": "pixeltools.ru",
        "group_id": "1",
        "frequency": "1000",
        "frequency_type": "exact"
    },
    {
        "id": "8797229",
        "query": "pixeltools.ru",
        "group_id": "22150",
        "frequency": "1000",
        "frequency_type": "exact"
    }
]

Добавление запросов

GET /projects/api/v1/queries/set

Добавляет фразы в проект и при необходимости привязывает их к группе и продвигаемому URL. Фразы, которые в проекте уже есть, повторно не создаются, но группа и URL к ним применяются. После добавления новых запросов делается то же, что в интерфейсе: запускается сбор частот, сбрасываются кэши, в сводку проекта пишется событие.

Без group и group_id новые запросы попадают в «Общую» (id 1), а группы уже существующих не меняются.
С группой и group_mode=replace (по умолчанию) у каждой переданной фразы снимаются все прежние группы. group_mode=add добавляет группу к прежним.

Все параметры читаются только из query-строки, в том числе при POST. URL применяется ко всем переданным фразам, включая уже существующие: без url продвигаемый URL у них сбросится.

Параметры query

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

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

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

Фразы через |. Чистятся от спецсимволов и лишних пробелов, регистр сохраняется.
group string

Название группы. Если в проекте такой нет — создаётся. «Общая» указывает на системную группу (id 1).
group_id int

ID группы из groups/get: своя группа проекта или «Общая». Приоритетнее group, новых групп не создаёт.
group_mode string

Что делать с прежними группами фраз, когда группа задана.

replace
заменить: фраза останется только в указанной группе

add
добавить: прежние группы сохранятся

По умолчанию replace
url string

Продвигаемый URL для всех переданных фраз.

Ответ

При успехе — ID и текст последней фразы из списка, без обёртки status/result. Формат исторический, сохранён ради совместимости. ID остальных фраз — в queries/get.

id int

ID последней фразы.
query string

Последняя фраза после очистки.

GET /projects/api/v1/queries/set

curl -G 'https://tools.pixelplus.ru/projects/api/v1/queries/set' \
  --data-urlencode 'token=ВАШ_КЛЮЧ' \
  --data-urlencode 'project_id=7002' \
  --data-urlencode 'queries=купить диван|диван недорого' \
  --data-urlencode 'group=Коммерческие' \
  --data-urlencode 'url=https://example.ru/catalog/divany/'

<?php
$url = 'https://tools.pixelplus.ru/projects/api/v1/queries/set?' . http_build_query([
    'token' => 'ВАШ_КЛЮЧ',
    'project_id' => 7002,
    'queries' => 'купить диван|диван недорого',
    'group' => 'Коммерческие',
    'url' => 'https://example.ru/catalog/divany/',
]);

$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/queries/set",
    params={
        "token": "ВАШ_КЛЮЧ",
        "project_id": 7002,
        "queries": "купить диван|диван недорого",
        "group": "Коммерческие",
        "url": "https://example.ru/catalog/divany/",
    },
    timeout=60,
)
print(response.json())

project_id обязательный ID проекта. Виден в адресе страницы проекта и в ответе projects/get queries обязательный Фразы через | group Название группы url Продвигаемый URL для всех переданных фраз

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

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

{
    "id": 12052800,
    "query": "диван недорого"
}

Удаление запросов

POST /projects/api/v1/queries/delete

Ставит удаление запросов в очередь и сразу отвечает. Запросы удаляются в фоне вместе с историей позиций, безвозвратно. ID, которые не принадлежат проекту, молча отбрасываются — в count только запросы этого проекта.

project_id и queries_id читаются из JSON-тела, формы или query-строки (в форме и query — queries_id[]=…). token — только из query-строки.

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

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

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

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

Массив ID запросов из queries/get.

Ответ

result.status string

Всегда ok.
result.message string

Удаление поставлено в очередь.
result.count int

Сколько запросов будет удалено.

POST /projects/api/v1/queries/delete

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

<?php
$url = 'https://tools.pixelplus.ru/projects/api/v1/queries/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,
        'queries_id' => [
            8797228,
            8797229,
        ],
    ]),
    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/queries/delete",
    params={
        "token": "ВАШ_КЛЮЧ",
    },
    json={
        "project_id": 7002,
        "queries_id": [
            8797228,
            8797229,
        ],
    },
    timeout=60,
)
print(response.json())

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

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

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

{
    "status": "ok",
    "code": 1,
    "msg": "success",
    "result": {
        "status": "ok",
        "message": "Удаление запросов поставлено в очередь",
        "count": 2
    }
}

Ошибки

Код	Сообщение	Когда
`50`	`access error`	Токен не передан, не найден, или у его владельца нет доступа к проекту.
`51`	`wrong project id`	`delete`: не передан `project_id`.
`52`	`Queries limit exceeded: max N per project`	`set`: новые фразы не помещаются в лимит запросов проекта. Ничего не добавлено. Ответ без обёртки: `{"error": "Queries limit exceeded: max 1000 per project", "code": 52, "max": 1000, "total": 998}`, где `total` — запросов в проекте сейчас.
`53`	`wrong queries ids`	`delete`: `queries_id` пуст, не массив или ни один ID не принадлежит проекту.
`53`	`Group is not available for this project`	`set`: `group_id` — чужая группа, группа URL или несуществующая. Ответ без обёртки: `{"error": "…", "code": 53}`.
`54`	`service unavailable`	`delete`: очередь недоступна, удаление не поставлено. Повторите позже.

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

{
    "status": "error",
    "code": 50,
    "msg": "access error",
    "result": []
}

Лимит числа запросов

queries/set проверяет тот же лимит запросов в проекте, что интерфейс: на тарифе «Стажёр» свой потолок, на остальных — общий. Считаются только фразы, которых в проекте ещё нет. Если не помещаются, не добавляется ни одна.

Формат ответа

get и set отдают данные без обёртки status/result, delete — в обёртке. Ошибки set — тоже без обёртки, с полями error и code. HTTP-код всегда 200.

Группами запросов управляют методы groups: создание, удаление, перенос запросов между группами.

queries Поисковые запросы проекта

Список запросов

Параметры query

Ответ

Добавление запросов

Параметры query

Ответ

Удаление запросов

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

Ответ

Ошибки

Лимит числа запросов

Формат ответа

`queries` Поисковые запросы проекта