Общая информация #
Раздел посвящен описанию методов API и их интерфейсов. API можно разделить на 2 большие части, это данные и справочники.
В этом разделе не будет приводиться информация о базовых параметрах запросов, а также полные структуры ответов. Для получения этой информации перейдите в раздел Работа с API.
Все методы принимают 2 не обязательных параметра:
| Параметр | Описание | Значение по умолчанию |
|---|---|---|
| limit | Количество возвращаемых результатов, максимум 10000 | 1000 |
| offset | Cмещение по списку | 0 |
GET: api/v1/projects?{ops} #
Возвращает список, доступных пользователю, проектов.
Входные параметры #
Специальных параметров не требуется.
Возвращаемый результат #
В поле data будет возвращен массив объектов следующего вида:
{
id: number
name: string
url: string
}GET: api/v1/rivals #
api/v1/rivalsВозвращает конкурентов проекта с видимостью в поисковой системе на последнюю дату проверки. По умолчанию — только отслеживаемые конкуренты, отсортированные по убыванию видимости.
Входные параметры #
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
| projectId | number | да | — | ID проекта |
| limit | number | нет | 1000 | Лимит записей (1–10000) |
| offset | number | нет | 0 | Смещение |
| fullList | boolean | нет | false | true — все конкуренты проекта, false — только отслеживаемые |
| neuralNetworkId | number | нет | первая включённая нейросеть проекта | ID нейросети проекта |
| order | string | нет | [«visibility»,»desc»] | Сортировка, JSON-массив (см. ниже) |
Сортировка #
Параметр order передаётся в строке запроса как JSON-массив из двух элементов:
["<поле>", "<направление>"]. Направление необязательно, по умолчанию
desc.
| Параметр | Формат | Пример |
|---|---|---|
| order | [«<поле>», «asc|desc»] | [«visibility»,»desc»],[«host»,»asc»] |
Допустимые поля: id, host, tracked, visibility. Недопустимое поле или направление игнорируется: используется сортировка по умолчанию (visibility desc). Если order не передан — сортировка по умолчанию. Невалидный JSON или значение, не являющееся массивом, — ошибка 400.
Поля ответа #
| Поле | Тип | Описание |
|---|---|---|
| id | number | ID конкурента |
| host | string | Домен конкурента |
| tracked | boolean | Признак отслеживания |
| visibility | number | Видимость в поисковике, % (0 — данных нет) |
| statTypeId | number | ID типа частотности; 0, если данных видимости нет |
| checkDate | string | null | Дата проверки, YYYY-MM-DD; null, если проверки на эту дату нет |
Пример #
curl -G "https://seo.alfastat.ru/api/v1/rivals" \
--data-urlencode "projectId=1445" \
--data-urlencode "engineId=12" \
--data-urlencode "statTypeId=5" \
--data-urlencode 'order=["visibility","desc"]' \
-H "Authorization: Bearer: <token>"
Возвращаемый результат #
В поле data будет возвращен массив объектов следующего вида:
{
"status": "ok",
"data": [
{"id": 481, "host": "rival.example.com", "tracked": true,
"visibility": 41.73, "statTypeId": 5, "checkDate": "2026-11-08"},
{"id": 482, "host": "another.example.com", "tracked": false,
"visibility": 17.02, "statTypeId": 5, "checkDate": "2026-11-08"}
]
}GET: api/v1/pages?{ops} #
Возвращает список страниц проекта.
Входные параметры #
| Параметр | Описание | Значение по умолчанию |
|---|---|---|
| project_id | id проекта | нет |
Возвращаемый результат #
В поле data будет возвращен массив объектов следующего вида:
{
id: number
name: string
url: string
categoryId: number
}GET: api/v1/engines?{ops} #
Возвращает список поисковых систем проекта.
Входные параметры #
| Параметр | Описание | Значение по умолчанию |
|---|---|---|
| project_id | id проекта | нет |
Возвращаемый результат #
В поле data будет возвращен массив объектов следующего вида:
{
id: number
searcher: 'Yandex'|'Google'
region: string
device: 'pc'|'mob'
fullName: string
resultType: 'search'|'product'|'insearch_ai'|'local_pack'
}| Поле | Описание |
|---|---|
| fullName | Полное имя поисковой сети, как отображается в интерфейсе (например Yandex Москва PC, Google AI Overview Москва Mob) |
Типы выдачи #
Поле resultType может принимать 4 значения:
| Тип | Описание |
|---|---|
| search | Обычная выдача |
| product | Товарные/торговые (Yandex.Товары / Google Merchant) |
| insearch_ai | Нейроблок (Алиса / AI Overview) |
| local_pack | Google Local Pack |
Типы частотности #
Возвращаемая частотность может быть 4х типов:
| Тип | Описание | Поисковая машина |
|---|---|---|
| 1 | Частота | |
| 5 | Частота | Yandex |
| 6 | «Частота» | Yandex |
| 8 | «!Частота» | Yandex |
GET: api/v1/categories?{ops} #
Возвращает список категорий (разделов) проекта.
Входные параметры #
| Параметр | Описание | Значение по умолчанию |
|---|---|---|
| project_id | id проекта | нет |
Возвращаемый результат #
В поле data будет возвращен массив объектов следующего вида:
{
id: number
name: string
}GET: api/v1/checks?{ops} #
Возвращает список проверок проекта.
Входные параметры #
| Параметр | Описание | Значение по умолчанию |
|---|---|---|
| project_id | id проекта | нет |
Возвращаемый результат #
В поле data будет возвращен массив объектов следующего вида:
{
id: number
checkDate: string
serpEngineId: number
engineName: string
}GET: api/v1/ai-visibility/networks?{ops} #
Возвращает список нейросетей, подключённых для проверки в проекте («Видимость в AI»).
Входные параметры #
| Параметр | Описание | Значение по умолчанию | Обязательный |
|---|---|---|---|
| project_id | id проекта | нет | да |
| limit | Количество записей в ответе, максимум 10000 | 1000 | нет |
| offset | Смещение списка | 0 | нет |
Возвращаемый результат #
В поле data будет возвращён массив объектов следующего вида:
{
id: number,
name: string,
code: string
}| Поле | Описание |
|---|---|
| id | id нейросети |
| name | Название нейросети: ChatGPT, Алиса AI, DeepSeek, Perplexity |
| code | Код нейросети: chatgpt, alice, deepseek, perplexity |
GET: api/v1/ai-visibility/checks?{ops} #
Возвращает список завершённых съёмов «Видимости в AI» по проекту, отсортированный по дате по убыванию.
Входные параметры #
| Параметр | Описание | Значение по умолчанию | Обязательный |
|---|---|---|---|
| project_id | id проекта | нет | да |
| limit | Количество записей в ответе, максимум 10000 | 1000 | нет |
| offset | Смещение списка | 0 | нет |
Возвращаемый результат #
В поле data будет возвращён массив объектов следующего вида:
{
id: number,
date: string
}| Поле | Описание |
|---|---|
| id | id съёма |
| date | Дата съёма в формате YYYY-MM-DD |
GET: api/v1/ai-rivals?{ops} #
Возвращает конкурентов проекта с видимостью в ответах нейросети на последнюю дату проверки. По умолчанию — только отслеживаемые конкуренты, отсортированные по убыванию видимости.
Параметры #
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
| projectId | number | да | — | ID проекта |
| limit | number | нет | 1000 | Лимит записей (1–10000) |
| offset | number | нет | 0 | Смещение |
| fullList | boolean | нет | false | true — все конкуренты проекта, false — только отслеживаемые |
| neuralNetworkId | number | нет | первая включённая нейросеть проекта | ID нейросети проекта |
| order | string | нет | [«visibility»,»desc»] | Сортировка, JSON-массив (см. ниже) |
Сортировка #
Форматorder совпадает с /rivals:
["<поле>", "asc|desc"], направление по умолчанию desc.
Допустимые поля: id, host, brandNames,
tracked, visibility.
| Параметр | Формат | Пример |
|---|---|---|
| order | [«<поле>», «asc|desc»] | [«visibility»,»desc»],[«host»,»asc»] |
Поля ответа #
| Поле | Тип | Описание |
|---|---|---|
| id | number | ID конкурента |
| host | string | Домен конкурента |
| brandNames | string | null | Бренды конкурента через запятую |
| tracked | boolean | Признак отслеживания |
| visibility | number | Видимость в ответах нейросети, % (0 — данных нет) |
Пример #
curl -G "https://seo.alfastat.ru/api/v1/ai-rivals" \
--data-urlencode "projectId=1445" \
--data-urlencode "neuralNetworkId=1" \
--data-urlencode 'order=["visibility","desc"]' \
-H "Authorization: Bearer: <token>"
Возвращаемый результат #
В поле data будет возвращён массив объектов следующего вида:
{
"status": "ok",
"data": [
{"id": 12, "host": "rival.example.com", "brandNames": "Example",
"tracked": true, "visibility": 34.21},
{"id": 13, "host": "another.example.com", "brandNames": "Another",
"tracked": false, "visibility": 12.05}
]
}Коды ошибок #
| Код | Причина |
|---|---|
| 400 | Невалидные параметры: нет projectId, limit вне 1–10000, offset < 0, а также некорректная JSON-строка в order (не JSON или не массив) |
| 401 | Не авторизован |
| 403 / 404 | Нет доступа к проекту или проект не найден; для /rivals — поисковик не найден; для /ai-rivals — нейросеть не найдена; 404 также — нет данных проверки |
| 429 | Слишком много запросов (лимит 5 запросов/сек, 120/мин) |
| 500 | Внутренняя ошибка |