Спидтест Мониторинг Личный кабинет →
Документация› API и интеграции› Обзор публичного API
Обновлено 22.10.2026 ≈ 3 мин чтения 37 просмотров

Обзор публичного API

OpenSpeedTest предоставляет REST API для программного доступа к списку тестовых серверов, отправки результатов измерений и получения агрегированной статистики. API работает по HTTPS и возвращает JSON в кодировке UTF-8.

Базовый URL

https://openspeedtest.ru

Версии и эндпоинты

МетодПутьНазначениеАвторизация
GET/api.php?action=get-serversСписок тестовых серверовX-API-KEY (обязательно)
POST/api.php?action=submit-resultОтправка результата тестаX-API-KEY + X-SIGNATURE
GET/api/v2/serversПерсональный список серверов + лимитыX-API-KEY
GET/api/v1/network-qualityАгрегированная статистика по регионам (карта)нет
GET/api/v1/network-quality/geometryГеометрия карты (TopoJSON)нет
Документация охватывает публичный серверный API. API мобильного приложения и встраиваемого виджета в этот раздел не входит.

Формат данных

  • Все ответы — JSON (Content-Type: application/json; charset=utf-8).
  • Тела POST-запросов передаются как JSON.
  • Успешные ответы обычно содержат поле success: true; ошибки — success: false и error с описанием.
  • Публичные эндпоинты статистики (network-quality) возвращают объект данных без поля success.

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

Основной способ — заголовок:

X-API-KEY: <64 hex-символа>

Ключ создаётся только в личном кабинете после регистрации. У ключа могут быть ограничения:

  • allowed_ip — список IP, с которых разрешена отправка результатов из CLI;
  • allowed_domains — список доменов, с которых разрешена работа виджета.

Отправка результата дополнительно подписывается HMAC-SHA256 (заголовок X-SIGNATURE) — см. статью «Отправка результата теста».

Защита каталога серверов

Список тестовых серверов является ресурсом сервиса и не отдаётся анонимно: запрос get-servers без действующего X-API-KEY получает 401. Такой подход позволяет:

  • выдавать каталог только идентифицированным клиентам;
  • привязывать ключ к домену (виджет) или IP (CLI), учитывать и ограничивать запросы;
  • отзывать доступ, удаляя ключ в личном кабинете;
  • не публиковать статические выгрузки каталога (они закрыты на уровне веб-сервера).

Ключ оформляется в личном кабинете после регистрации — см. статью «API-ключи».

Квоты

Ключи, привязанные к аккаунту, делят единую квоту аккаунта (окна «час» и «сутки»). Превышение лимита возвращает 429 с заголовком Retry-After. Отдельно действует защитный лимит для submit-result. Подробности — в статье «Квоты и лимиты».

Коды ошибок (общие)

КодЗначение
400Некорректный запрос: параметр, тело или action
401Не передан X-API-KEY
403Ключ недействителен/неактивен, домен или IP не разрешены, неверная подпись
404Ресурс/эндпоинт недоступен
405Недопустимый HTTP-метод
429Превышение квоты или защитного лимита
500Внутренняя ошибка сервера
503Функция временно недоступна

CORS

Эндпоинт api.php добавляет CORS-заголовки: при наличии Origin он возвращается в Access-Control-Allow-Origin вместе с Access-Control-Allow-Credentials: true, без Origin — Access-Control-Allow-Origin: *. Preflight OPTIONS разрешает методы GET, POST, OPTIONS и заголовки Content-Type, X-API-KEY, X-SIGNATURE, Origin, Referer. Эндпоинты api/v2 и network-quality рассчитаны на запросы с того же источника и CORS-заголовков не добавляют.

Ограничения

  • Свежесть запроса: при отправке результата timestamp не должен отличаться от серверного времени более чем на 300 секунд.
  • Определение IP: сервис учитывает заголовки X-Forwarded-For и X-Real-IP (за обратным прокси), иначе — REMOTE_ADDR.
  • Версии: контракт api.php стабилен; новые возможности добавляются в api/v2 и публичные эндпоинты статистики. Требование API-ключа для get-servers — часть политики защиты каталога серверов.