ZOV API v1 · ZOV Platform · JSON · IPv4 / IPv6
Источники: X4B VPN feeds (MIT, © 2024 X4B/Mathew Heard), monosans proxy-list (MIT, © 2022 monosans), Tor Project и RIPE NCC. Отдельный ежедневный сканер проверяет найденные endpoints через контролируемый сервер ZOV; результаты доступны в Services.
Создайте ключ в dashboard с правом ip:read. Передавайте его только в заголовке Authorization. Базовый адрес: https://api.zov.lat/v1, либо /v1 на основном сайте.
curl 'https://api.zov.lat/v1/ip/8.8.8.8?fields=ip,asn,tor' \ -H 'Authorization: Bearer YOUR_API_KEY'
fields выбирает поля и вложенные пути; exclude применяется после fields. include=sources,history,abuse включает дополнительные данные с проверкой разрешений. missing=omit|null|include_status управляет неизвестными значениями. sources принимает только зарегистрированные ID: tor,ripe,x4b_vpn4,x4b_vpn6,x4b_hosting4,x4b_hosting6,internet_scanner,proxy_http,proxy_socks4,proxy_socks5,dbip,aws,gcloud,rdap, не URL.
risk_score: 0–100, оценка риска по наблюдениям, не вероятность. VPN: положительное совпадение с X4B VPN feed (IPv4/IPv6). Proxy: совпадение с опубликованным HTTP/SOCKS feed monosans. Совпадения со списками — сведения источника. internet_scanner означает успешную активную проверку подписанного ответа с контролируемого origin за последние 36 часов. Tor: true только при свежем положительном совпадении. Во всех списках отсутствие даёт null. GeoIP: DB-IP Country Lite (CC BY 4.0, сниженная точность, без города). ML pipeline подключён; прогноз доступен только после публикации оценённой модели.
Квоты ключа: 60 запросов/мин, 10 000/день, 100 000/месяц. Batch: максимум 50 IP, 5 запросов/мин на аккаунт, поэлементные ошибки. Экспорт CSV/NDJSON/JSON: GET /exports/{kind}, до 1000 записей, exports:create, 10 экспортов/час.
Ключ хранится только в состоянии страницы и передаётся в заголовке. На основном сайте можно использовать текущую сессию; на docs.zov.lat нужен API-ключ.
| Endpoint | Разрешение | Описание |
|---|---|---|
| GET /ip/{ip} | ip:read | IP Lookup |
| POST /ip/batch | ip:batch | { ips: ["8.8.8.8", "::1"], fields: ["ip", "tor"] } |
| GET /ip/{ip}/history | ip:history:read | Версии наблюдений |
| GET /asn/{asn} | asn:read | Наблюдаемые адреса ASN |
| GET /abuse/{ip} | abuse:read | Официальные abuse контакты |
| GET /stats/overview | stats:read | Агрегаты |
| GET /stats/timeseries?days=7 | stats:read | Временные ряды |
| GET, POST /allowlist и /denylist | rules:read, allowlist:write, denylist:write | IP/CIDR |
| GET, POST /rules | rules:read/write | name, conditions, action, priority |
| POST /rules/preview | rules:read | Dry-run на последних 1000 наблюдениях |
| GET, POST /events | events:read/write | События пользователя |
| GET, POST /analytics/reports | analytics:reports:read/write | Приватные конфигурации отчётов |
| POST /analytics/reports/{id}/run | analytics:reports:read | Результат и ID запуска |
| GET /status/summary | Публично | Статус компонентов |
| GET /health/ready | Публично | PostgreSQL и Redis |
Все маршруты и схемы доступны в OpenAPI. SDK и Minecraft-плагин доступны ниже.
Скачать SDK: Python, TypeScript, Rust, Java и исходники Paper · Minecraft Paper-плагин · Установка и примеры
IP-фильтры: country, continent, asn, category, confidence_min/max, from/to. Пагинация: limit ≤100, meta.pagination.next_cursor передаётся как cursor. При cursor сортировка по IP стабильна; IP Desc задаётся sort=ip_desc.
Analytics: GET /analytics/registry, POST /analytics/query; конфигурации и фоновые запуск/история в /analytics/reports. Webhooks настраиваются в кабинете: подписанная доставка с HMAC-SHA256 и пятью попытками. Проверяйте timestamp, подпись и повторный event ID.
Ответ: { data, meta: { request_id, api_version, generated_at, cached } }. Ошибка: { error: { code, message, request_id, details } }. HTTP: 401 — ключ/сессия, 403 — разрешение, 404 — запись, 409 — конфликт, 422 — валидация, 429 — квота, 503 — зависимость недоступна.
Приватные списки, события, отчёты и usage изолированы по аккаунту. IP и история общих публичных источников доступны авторизованным аккаунтам. Политики вычисляются для владельца ключа. При отсутствии совпадения — REVIEW.