Geliştirici API

Yakında

Konumların etrafındaki canlı ve geçmiş yıldırımlar için bir REST API. Aşağıda planlanan sözleşme; üretim sunumu backend ile gelir.

Temel URL:https://api.zappollo.appv1

Tüm uç noktalar /v1 altında. Kırıcı değişiklikler kullanımdan kaldırma süresiyle yeni sürüm olarak gelir.

Kimlik doğrulama

API anahtarını bearer token olarak gönder:

Authorization: Bearer zpk_live_…

Hızlı başlangıç

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"

Uç noktalar

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).

Örnek yanıt

{
  "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
}

Temel kavramlar

Hatalar

type, status ve request_id ile tutarlı problem+json (RFC 7807).

Sayfalama

İmleç tabanlı — yanıttaki "next" değerini ?cursor olarak geç.

Hız limitleri

Anahtar başına kotalar; X-RateLimit-* başlıklarına bak.

İdempotentlik

Yazma işlemlerinde Idempotency-Key başlığı gönder; yeniden denemeler güvenli olsun.

Hatalar · 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"
}

Webhook'lar

Bir geofence abone ol ve imzalı POST'lar al. X-Zappollo-Signature HMAC'ini doğrula.

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'lar ve araçlar

Resmi JavaScript/TypeScript ve Python SDK'ları, bir Postman koleksiyonu ve OpenAPI 3 spesifikasyonu.

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

Bir şey mi geliştiriyorsun? Etkinliğin veya platformun için API anahtarı al.

API erişimi iste

Zapollo · OpenStreetMap · OpenWeather · Blitzortung.org