API ключевых слов

API для управления ключевыми словами в системе Revo. Ключевые слова являются частью проектов и определяют поисковые запросы, по которым производится продвижение.

Структура ключевого слова

Поле	Тип	Описание
id	integer	Уникальный идентификатор ключевого слова
keyword	string	Текст ключевого слова (поисковый запрос)
url	string	URL целевой страницы (если отличается от основного домена)
group	string	Группа для организации ключевых слов
active	boolean	Статус активности ключевого слова
clicks	integer	Количество кликов, выделяемых на данное ключевое слово
interval	integer	Интервал между кликами в секундах
condition_position	integer	Минимальная позиция для проклика
target_position	integer	Целевая позиция
frequency	integer	Частота запросов по данному ключевому слову
search_hint	string	Подсказка для поиска сайта
last_clicked_at	datetime	Дата и время последнего клика
user_id	integer	ID владельца
project_id	integer	ID проекта
created_at	datetime	Дата создания
updated_at	datetime	Дата обновления

Получение списка ключевых слов

GET /api/v1/project/{projectId}/keywords?limit=50&offset=0

Параметры запроса

Параметр	Тип	Обязательный	Описание
projectId	integer	Да	ID проекта (в URL)
limit	integer	Нет	Количество ключевых слов в ответе (по умолчанию 50)
offset	integer	Нет	Смещение для пагинации (по умолчанию 0)

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

{
    "error": "",
    "result": [
        {
            "id": 1,
            "keyword": "купить смартфон недорого",
            "url": "https://example.com/smartphones",
            "group": "смартфоны",
            "active": true,
            "clicks": 5,
            "interval": 60,
            "condition_position": 1,
            "target_position": 1,
            "frequency": 1000,
            "search_hint": "интернет-магазин",
            "last_clicked_at": "2025-01-01T00:00:00.000000Z",
            "user_id": 1,
            "project_id": 1,
            "created_at": "2025-01-01T00:00:00.000000Z",
            "updated_at": "2025-01-02T00:00:00.000000Z"
        }
    ],
    "total": 1
}

Добавление ключевого слова

POST /api/v1/project/{projectId}/keywords

Параметры запроса

Параметр	Тип	Обязательный	Описание
projectId	integer	Да	ID проекта (в URL)
keyword	string	Да	Текст ключевого слова
url	string	Нет	URL целевой страницы
group	string	Нет	Группа для организации (по умолчанию "default")
active	boolean	Нет	Статус активности (по умолчанию true)
clicks	integer	Нет	Количество кликов (по умолчанию 0)
interval	integer	Нет	Интервал в секундах (по умолчанию 60)
condition_position	integer	Нет	Минимальная позиция (по умолчанию 1)
target_position	integer	Нет	Целевая позиция (по умолчанию 1)
frequency	integer	Нет	Частота запросов
search_hint	string	Нет	Подсказка для поиска

Пример запроса

{
    "keyword": "купить смартфон недорого",
    "url": "https://example.com/smartphones",
    "group": "смартфоны",
    "clicks": 5,
    "interval": 120
}

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

{
    "error": "",
    "result": {
        "id": 1,
        "keyword": "купить смартфон недорого",
        "url": "https://example.com/smartphones",
        "group": "смартфоны",
        "active": true,
        "clicks": 5,
        "interval": 120,
        "condition_position": 1,
        "target_position": 1,
        "user_id": 1,
        "project_id": 1,
        "created_at": "2025-01-01T00:00:00.000000Z",
        "updated_at": "2025-01-01T00:00:00.000000Z"
    }
}

Массовое добавление ключевых слов

POST /api/v1/project/{projectId}/keywords/mass

Параметры запроса

Параметр	Тип	Обязательный	Описание
projectId	integer	Да	ID проекта (в URL)
keywords	array	Да	Массив объектов ключевых слов
keywords.*.keyword	string	Да	Текст ключевого слова
keywords.*.url	string	Нет	URL целевой страницы
keywords.*.group	string	Нет	Группа для организации
keywords.*.active	boolean	Нет	Статус активности
keywords.*.clicks	integer	Нет	Количество кликов
keywords.*.interval	integer	Нет	Интервал в секундах
keywords.*.condition_position	integer	Нет	Минимальная позиция
keywords.*.target_position	integer	Нет	Целевая позиция
keywords.*.frequency	integer	Нет	Частота запросов
keywords.*.search_hint	string	Нет	Подсказка для поиска

Пример запроса

{
    "keywords": [
        {
            "keyword": "купить смартфон недорого",
            "url": "https://example.com/smartphones",
            "group": "смартфоны"
        },
        {
            "keyword": "купить планшет дешево",
            "url": "https://example.com/tablets",
            "group": "планшеты"
        }
    ]
}

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

{
    "error": "",
    "result": {
        "message": "Ключевые слова успешно добавлены",
        "count": 2
    }
}

Обновление ключевого слова

PUT /api/v1/project/{projectId}/keywords/{id}

Параметры запроса

Параметр	Тип	Обязательный	Описание
projectId	integer	Да	ID проекта (в URL)
id	integer	Да	ID ключевого слова (в URL)

Остальные параметры аналогичны параметрам создания ключевого слова, но ни один из них не является обязательным.

Пример запроса

{
    "clicks": 10,
    "interval": 180,
    "active": false
}

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

Аналогичен ответу на создание ключевого слова, с обновленными полями.

Удаление ключевого слова

DELETE /api/v1/project/{projectId}/keywords/{id}

Параметры запроса

Параметр	Тип	Обязательный	Описание
projectId	integer	Да	ID проекта (в URL)
id	integer	Да	ID ключевого слова (в URL)

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

{
    "error": "",
    "result": {
        "message": "Ключевое слово успешно удалено"
    }
}

Активация ключевых слов

POST /api/v1/project/{projectId}/keywords/enable

Параметры запроса

Параметр	Тип	Обязательный	Описание
projectId	integer	Да	ID проекта (в URL)
keywords	array	Да	Массив ID ключевых слов для активации

Пример запроса

{
    "keywords": [1, 2, 3]
}

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

{
    "error": "",
    "result": {
        "message": "Ключевые слова активированы"
    }
}

Деактивация ключевых слов

POST /api/v1/project/{projectId}/keywords/disable

Параметры запроса

Параметр	Тип	Обязательный	Описание
projectId	integer	Да	ID проекта (в URL)
keywords	array	Да	Массив ID ключевых слов для деактивации

Пример запроса

{
    "keywords": [1, 2, 3]
}

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

{
    "error": "",
    "result": {
        "message": "Ключевые слова деактивированы"
    }
}

Дополнительная информация

Поля condition_position и target_position

• condition_position - определяет минимальную позицию сайта, при которой система будет производить клик
• target_position - определяет целевую позицию, к которой стремится система

Поле frequency

Показывает примерную частоту запросов по данному ключевому слову в месяц (согласно данным поисковых систем).

Поле search_hint

Переопределяет глобальную подсказку, заданную на уровне проекта. Если задана, используется вместо подсказки проекта.