#Обзор

Spectrum API — единый шлюз для поиска по открытым данным. Поддерживает 12 типов поиска: от ФИО до VIN-номера.

Базовый URL: https://api.usespectrum.cfd
Все эндпоинты возвращают JSON. Кодировка ответа — UTF-8.

#Авторизация

Для доступа к API требуется ключ. Передавайте его одним из двух способов.

X-API-Key
рекомендуется
HTTP-заголовок
Передаётся в заголовке запроса. Безопаснее, чем query-параметр.
?key=
Query-параметр
Передаётся в URL. Удобно для тестирования через curl/браузер.
Безопасность: Никогда не используйте API-ключ в клиентском JavaScript на сайтах — он будет виден в коде. Всегда проксируйте запросы через свой сервер.

#Endpoints

Все доступные методы API.

GET/api/v1/search?q={запрос}&type={тип}Поиск по данным
GET/api/v1/check-keyПроверить статус ключа

Параметры /search

ПараметрТипОбязательныйОписание
qstringДаПоисковый запрос
typestringНетТип поиска (по умолчанию: fio)
keystring*API-ключ (если не передан в заголовке)

Типы поиска

ТипОписание
fioПоиск по ФИО
phoneПоиск по номеру телефона
passportПоиск по паспорту
snilsПоиск по СНИЛС
innПоиск по ИНН
tgidПоиск по Telegram ID
carПоиск по автомобилю
vinПоиск по VIN
ogrnПоиск по ОГРН
ogrnipПоиск по ОГРНИП
emailПоиск по email
addressПоиск по адресу

#Ошибки

API возвращает стандартизированные HTTP-статусы и JSON с описанием ошибки.

HTTPСообщениеОписание
400Параметр q обязателенНе передан поисковый запрос
401Требуется API-ключКлюч не указан ни в заголовке, ни в URL
403Неверный API-ключКлюч не найден в базе
403Срок действия ключа истёкКлюч просрочен
429Превышен лимит. Пауза X мин.Rate limit + strike-система
500ошибка на стороне сервераВнутренняя ошибка сервера

Strike-система

При превышении лимита в 100 запросов/минуту включается прогрессивный кулдаун:

НарушениеДлительность
1-е5 минут
2-е10 минут
3-е30 минут
4+60 минут
После окончания кулдауна счётчик обнуляется. Система начинается заново с 5 минут.

#Лимиты

Ограничения на использование API.

ЛимитЗначениеДетали
Запросов в минуту100На один API-ключ
Кулдаун5 — 60 минПрогрессивный при превышении
Срок ключа7 / 30 / 365 дн.Или бессрочно по запросу
Хотите увеличить лимит? Обратитесь к администратору. Индивидуальные условия для партнёров и бизнес-клиентов.

#Примеры

Готовые интеграции для вашего проекта.

Python — поиск по номеру телефона
import requests

API_KEY = "ваш_ключ"
BASE = "https://api.usespectrum.cfd"

response = requests.get(
    f"{BASE}/api/v1/search",
    params={"key": API_KEY, "q": "+79991234567", "type": "phone"},
)

if response.status_code == 200:
    print(response.json())
else:
    print("Ошибка:", response.status_code, response.text)
JavaScript (Fetch) — поиск по email
const API_KEY = 'ваш_ключ';
const email = 'user@example.com';

try {
  const res = await fetch(
    `https://api.usespectrum.cfd/api/v1/search?key=${API_KEY}&q=${encodeURIComponent(email)}&type=email`
  );
  const data = await res.json();

  if (data.success) {
    console.log('Результаты:', data.data);
  } else {
    console.error('Ошибка API:', data.error);
  }
} catch (err) {
  console.error('Сетевая ошибка:', err);
}

Правила использования

Нарушение правил ведёт к блокировке API-ключа без возврата средств.

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

Максимум 100 запросов в минуту на один ключ. При превышении — прогрессивный кулдаун от 5 до 60 минут. Увеличение лимита только через администратора.

Конфиденциальность ключа

Запрещается передавать API-ключ третьим лицам. Ключ предназначен строго для личного использования. При утечке ключ блокируется без предупреждения.

Использование данных

Полученные данные разрешается использовать только в личных целях. Публикация, перепродажа или передача данных третьим лицам строго запрещены.

Автоматизация

Разрешена только через официальный API-ключ. Парсинг, скрапинг через Telegram-бота, а также любые недокументированные методы запрещены.

Злоупотребление

DDoS-атаки, флуд, попытки взлома, подбора ключей или обхода системы авторизации ведут к немедленной и бессрочной блокировке.

Поддержка

По вопросам увеличения лимитов, ошибок, сотрудничества и индивидуальных условий — обращайтесь к администратору через Telegram.