API для разработчиков

Скоро

REST API для молний в реальном времени и истории вокруг ваших мест. Ниже — планируемый контракт; продакшен появится вместе с бэкендом.

Базовый URL:https://api.zappollo.appv1

Все эндпоинты под /v1. Несовместимые изменения выходят новой версией с периодом устаревания.

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

Передавайте API-ключ как bearer-токен:

Authorization: Bearer zpk_live_…

Быстрый старт

curl -H "Authorization: Bearer zpk_live_…" \
  "https://api.zappollo.app/v1/lightning?lat=48.2&lon=11.6&radius_km=50&since=2026-06-03T13:00:00Z"

Эндпоинты

Lightning core
GET/v1/lightning?bbox={w,s,e,n}&since={iso}&limit=1000

Recent strikes in a bounding box.

GET/v1/lightning?lat={lat}&lon={lon}&radius_km=50&since={iso}

Recent strikes within a radius.

POST/v1/lightning/query

Query by GeoJSON polygon, type (CG/IC), polarity and min peak current (kA).

GET/v1/lightning/history?lat=&lon=&radius_km=&from=&to=

Historical strikes for a point, radius and time range.

GET/v1/lightning/{id}

Full detail: kA, polarity, error ellipse, stations, confidence.

GET/v1/lightning/density?bbox=&cell=h3:7&since=

Gridded strike counts (H3/geohash) for heatmaps.

Nowcasting & storm cells
GET/v1/cells?bbox=

Active storm cells with centroid, intensity, heading and speed.

GET/v1/cells/{id}/forecast?minutes=60

0–60 min nowcast track + ETA to a point.

GET/v1/risk?lat=&lon=

Combined storm-risk score (lightning + precipitation + wind).

Real-time & safety
WSwss://stream.zappollo.app/v1/lightning?bbox=

Live strike stream over WebSocket.

GET/v1/stream/sse?bbox=

Live strike stream over Server-Sent Events.

POST/v1/alerts/subscribe

Geofence webhook subscription (signed deliveries).

GET/v1/safety?lat=&lon=&radius_km=13

Safety status: watch / warning / all-clear (30-30 rule).

Maps & tiles
GET/v1/tiles/density/{z}/{x}/{y}.png

Raster density tiles.

GET/v1/tiles/strikes/{z}/{x}/{y}.mvt

Vector tiles (MVT) of strikes and cells.

GET/v1/static?lat=&lon=&zoom=&w=800&h=600

Static map PNG snapshot (embeddable in reports).

Weather context
GET/v1/weather?lat=&lon=

Current conditions + short-term precipitation nowcast.

Reports & compliance
POST/v1/reports/verify

Was there a strike within R km of a point between T1–T2? Returns JSON + signed PDF.

GET/v1/reports/{id}

Fetch a generated report or strike certificate.

Analytics & bulk
GET/v1/stats?region=DE-BY&from=&to=&interval=hour

Aggregated counts and trends.

GET/v1/export?from=&to=&format=ndjson

Bulk export (enterprise).

Пример ответа

{
  "data": [
    {
      "id": "a1b2c3",
      "t": "2026-06-03T14:02:11.482Z",
      "lat": 48.214, "lon": 11.553,
      "type": "CG", "polarity": "-", "peak_kA": 14.2,
      "ellipse_km": 0.4, "stations": 9, "confidence": 0.97,
      "source": "certified-net"
    }
  ],
  "next": "c2Vfb2Zmc2V0PTEwMDA",
  "count": 1
}

Основные понятия

Ошибки

Единый problem+json (RFC 7807) с type, status и request_id.

Пагинация

По курсору — передавайте "next" из ответа как ?cursor.

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

Квоты на ключ; смотрите заголовки X-RateLimit-*.

Идемпотентность

Отправляйте заголовок Idempotency-Key при записи, чтобы повторы были безопасны.

Ошибки · problem+json
{
  "type": "https://docs.zappollo.app/errors/rate-limit",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "60 req/min exceeded. Retry after 12s.",
  "request_id": "req_8f2a91c4"
}

Вебхуки

Подпишите геозону и получайте подписанные POST. Проверяйте HMAC X-Zappollo-Signature.

POST https://your-app.com/hooks/zappollo
X-Zappollo-Signature: t=1717423331,v1=5e1b…

{ "event": "strike.near", "place_id": "venue-12",
  "strike": { "id": "a1b2c3", "distance_km": 7, "t": "…" } }

SDK и инструменты

Официальные SDK для JavaScript/TypeScript и Python, коллекция Postman и спецификация OpenAPI 3.

@zappollo/sdk (JS/TS)zappollo (Python)Postman collectionopenapi.yaml

Что-то создаёте? Получите API-ключ для вашего мероприятия или платформы.

Запросить доступ к API

Zapollo · OpenStreetMap · OpenWeather · Blitzortung.org