SimilarwebAPI | Документация API

SimilarwebAPI предоставляет 27 эндпоинтов данных только для чтения под /v1/similarweb. Используйте тот же аккаунт, ключ API, баланс и историю использования, что и для других API RequestBeam. Доступность зависит от включённого шлюза и разрешений ключа; документация не подтверждает доступность в продакшене.

Аутентификация

Передавайте свой ключ API RequestBeam, а не сторонние учётные данные:

http

Authorization: Bearer YOUR_API_KEY

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

Все публичные операции используют GET с параметрами запроса и без тела. Строго сохраняйте документированный регистр путей и параметров.

Поддерживаются только данные по всему миру (country=999). Другие допустимые значения страны заменяются на 999 перед запросом к поставщику; возвращаются мировые данные, а не данные указанной страны.

Для конечных точек, принимающих даты, допустимый полный явно заданный диапазон from/to имеет приоритет. Если конечная точка принимает latest, заданное значение по-прежнему проходит существующие проверки формата и допустимых значений, но не используется для выбора диапазона и не отправляется в Similarweb; значение latest по умолчанию не добавляется. Без явного диапазона прежние правила latest, значений по умолчанию и окон сохраняются. Ограничения History остаются в силе; конечные точки без поддержки latest по-прежнему отклоняют это поле.

bash

curl --get "https://api.apihop.ai/v1/similarweb/websites/incoming-referrals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "key=example.com" \
  --data-urlencode "country=999" \
  --data-urlencode "page=1"

Входящие переходы используют одно имя хоста в параметре key нижнего регистра, а не keys. Этот key — бизнес-параметр запроса для целевого сайта, а не учётные данные API; он разрешён только на специально разрешённых GET-маршрутах Similarweb. Аутентификация по-прежнему использует Authorization, остальные поля учётных данных в запросе запрещены. Строки возвращаются в Records, а не в Data. Точные поля каждой операции приведены в полном справочнике эндпоинтов.

Охват

Поиск: предложения ключевых слов, страницы в рейтинге, ключевые слова сайта, органический и платный поиск, брендовые ключевые слова.
Трафик сайта: вовлечённость, посещения, география, распределение устройств, каналы и социальный трафик.
Связи: обратные ссылки, входящие переходы, исходящий трафик и похожие сайты.
История: отдельные ряды месячных посещений, показателя отказов, длительности посещения и страниц за посещение.

Ответы

Успешные ответы сохраняют исходное тело JSON без новой оболочки success/data. Имена полей, неизвестные поля, пустые массивы и числовая точность не меняются. Разные эндпоинты могут возвращать Data, Records или другую исходную структуру; не предполагайте универсальное поле строк.

Успешный пустой результат не означает отсутствие трафика у домена. Неудачные запросы нельзя считать пустыми данными. Сохраняйте X-Request-Id и время запроса для диагностики.

Оплата и пагинация

Стандартная цена для всех 27 эндпоинтов — $0.0005 за успешный запрос, или $0.50 за 1,000 запросов. Оплата за запрос, а не за строку; успешный пустой результат всё равно считается одним запросом. Каждая следующая страница — отдельный запрос. Настроенные индивидуальные цены аккаунта имеют приоритет. Запросы с неверными параметрами, отсутствующей авторизацией или недостаточным балансом не выполняются как успешные оплачиваемые вызовы. Неудачные запросы к вышестоящему провайдеру не оплачиваются.

Согласно политике минимального баланса платформы, перед вызовом на аккаунте должно быть доступно минимум $0.10. Стандартная плата остаётся $0.0005 за успешный запрос.

Используйте только поля пагинации, документированные для выбранного эндпоинта. Нумерация обычно начинается с 1; обратные ссылки используют Page и PageSize, другие таблицы могут использовать page, pageSize или rowsPerPage. Не передавайте неподдерживаемые поля размера страницы.

Ошибки

Ошибки платформы имеют следующую структуру; code — бизнес-код платформы, а не HTTP-статус:

json

{"success":false,"error":{"code":10000,"message":"Invalid request parameters"},"requestId":"..."}

Типичные HTTP-статусы: 400 неверный запрос, 401 неверный ключ API, 402 недостаточный баланс, 403 доступ к шлюзу запрещён, 429 ограничение частоты и 5xx временный сбой провайдера или сервиса. Не повторяйте некорректные запросы без изменений.