API — przegląd

GEO Platform udostępnia publiczne REST API pod ścieżką /v1/. Zasada: wszystko, co pokazuje dashboard, można wyciągnąć jako dane. API służy do dostępu real‑time pod dashboardy i automatyzacje; do zrzutów masowych służą Eksport (CSV / JSONL) i BigQuery Sync.

• Base URL: https://geoplatform.pl/v1/
• Wersja: v1
• Format: JSON
• Uwierzytelnianie: nagłówek X-API-Key

Pełna referencja endpointów

Kompletna, interaktywna Referencja API (v1) jest generowana automatycznie z OpenAPI — każdy endpoint z parametrami, schematami odpowiedzi i gotowymi snippetami (curl / Python / Node.js). Spec do pobrania: /openapi/geo-v1.json.

Uwierzytelnianie

Klucze API tworzysz w panelu (sekcja Klucze API). Każde żądanie wysyła klucz w nagłówku:

curl -H "X-API-Key: geo_twoj_klucz" \
  https://geoplatform.pl/v1/visibility/summary

• Klucz jest workspace‑scoped i ma przypisane uprawnienia (scopes), np. visibility:read, products:read, attribution:read, brand-safety:read, orders:read, orders:write.
• Gating pakietowy jest nadrzędny nad scope — endpointy produktowe / atrybucji / brand‑safety wymagają, by pakiet obejmował daną funkcję (inaczej 403), niezależnie od scope klucza.

Format odpowiedzi

Nowsze endpointy zwracają spójną kopertę { data, meta }:

{
  "data": [ /* rekordy lub obiekt */ ],
  "meta": {
    "generated_at": "2026-07-19T10:30:00Z",
    "total": 42,
    "period_days": 30,
    "next_cursor": null
  }
}

Endpointy z pierwszej generacji zachowują swój dotychczasowy, płaski kształt (dla zgodności wstecznej).

Paginacja kursorowa

Listy, które mogą rosnąć, używają paginacji kursorowej:

curl -H "X-API-Key: geo_twoj_klucz" \
  "https://geoplatform.pl/v1/products?limit=50"
# w odpowiedzi: meta.next_cursor -> przekaż jako ?cursor=... po następną stronę

Kursor jest nieprzejrzysty (opaque) — przekazuj go bez modyfikacji.

Limity zapytań

Każdy klucz ma limit na minutę. Na każdej odpowiedzi zwracamy nagłówki, dzięki którym możesz się samoograniczać:

• X-RateLimit-Limit — limit na minutę,
• X-RateLimit-Remaining — pozostałe żądania w bieżącym oknie,
• X-RateLimit-Reset — sekundy do resetu okna.

Po przekroczeniu limitu API zwraca 429 Too Many Requests.

Błędy

Błędy zwracane są ze standardowymi kodami HTTP:

Kod	Znaczenie
401	brak / nieprawidłowy klucz API
403	brak scope lub funkcja spoza pakietu
404	zasób nie istnieje
429	przekroczony limit zapytań
400	nieprawidłowe parametry (np. zły kursor)

Przykładowe obszary danych

• Widoczność: GET /v1/visibility/summary, /visibility/timeseries, /visibility/questions
• Produkty: GET /v1/products, /products/visibility/summary, /products/share-of-shelf
• Atrybucja: GET /v1/attribution/revenue, /attribution/roi, /attribution/timeseries
• Brand Safety: GET /v1/brand-safety/hallucinations, /brand-safety/summary
• Zamówienia: POST /v1/orders, POST /v1/orders/batch, GET /v1/orders