Dokumentacja API Stat4Seo – Monitoring Pozycji Stat4Seo

Poniżej znajdziesz opis publicznego API do integracji Stat4Seo z innymi narzędziami. API jest proste, zwraca dane w formacie JSON i wymaga klucza API.

Uwierzytelnianie

Klucz API (wygeneruj w panelu Stat4Seo: Ustawienia → Ustawienia API).
Przekazuj klucz w jednym z miejsc:
Nagłówek: X-API-Key: TWÓJ_KLUCZ_API
Parametr zapytania: api_key=TWÓJ_KLUCZ_API

Adres bazowy

https://adres-do-panelu.domena.pl/api.php

Konwencje

Wszystkie odpowiedzi w JSON
Parametry zapytań w snake_case
Daty w formacie: YYYY-MM-DD
Jeżeli brak wartości/rekordu zwracany jest null

Wersjonowanie API

Parametr opcjonalny: version (int)
Domyślnie: 1 (pominięcie parametru = wersja 1)
Obsługiwane wersje: 1, 2
Nieobsługiwana wersja: 400 BAD_REQUEST z listą wspieranych wersji

Obsługa błędów

200: OK (poprawna odpowiedź)
400: BAD_REQUEST (np. brak wymaganych parametrów)
401: INVALID_API_KEY (brak/niepoprawny klucz)
404: NOT_FOUND (np. nieistniejąca strona)

Endpointy

1) Lista stron

Endpoint: endpoint=get_sites
Metoda: GET
Dodatkowe parametry: brak
Przykładowy URL:
https://adres-do-panelu.domena.pl/api.php?endpoint=get_sites&api_key=...

Struktura odpowiedzi:

{
  "sites": [
    {
      "id": 12,
      "url": "example.com",
      "engine": "Google.pl [Polska]",
      "category": {
        "id": 5,
        "name": "Sklepy"
      }
    },
    {
      "id": 34,
      "url": "example2.de",
      "engine": "Google.de",
      "category": null
    }
  ]
}

Opis pól:

id: ID strony
url: adres strony
engine: pełna nazwa wyszukiwarki (np. “Google.de”)
category: obiekt { id, name } lub null, gdy brak kategorii

2) Pozycje strony w wybranym zakresie dat

Endpoint: endpoint=get_site_positions
Metoda: GET
Parametry (wymagane):
site_id (int) — ID strony
date_from (string) — data początkowa YYYY-MM-DD
date_to (string) — data końcowa YYYY-MM-DD
Parametry dodatkowe (opcjonalne): version (int) — wersja API (1 lub 2, domyślnie 1)
Przykładowy URL:
https://adres-do-panelu.domena.pl/api.php?endpoint=get_site_positions&site_id=12&date_from=2025-08-01&date_to=2025-08-03&api_key=...
Przykładowy URL v2:
https://adres-do-panelu.domena.pl/api.php?endpoint=get_site_positions&site_id=12&date_from=2025-08-01&date_to=2025-08-03&version=2&api_key=...

Struktura odpowiedzi V1:

{
  "site": {
    "id": 12,
    "url": "example.pl",
    "engine": "Google.pl [Polska]",
    "category": {
      "id": 5,
      "name": "Sklepy"
    }
  },
  "keywords": [
    {
      "id": 101,
      "keyword": "przykładowa fraza",
      "forced_location": "Warszawa",
      "is_paused": false,
      "is_hidden": false,
      "category": {
        "id": 3,
        "name": "Brand"
      },
      "positions_by_date": {
        "2025-08-01": 12,
        "2025-08-02": null,
        "2025-08-03": 10
      }
    },
    {
      "id": 102,
      "keyword": "inna fraza",
      "forced_location": null,
      "is_paused": true,
      "is_hidden": false,
      "category": null,
      "positions_by_date": {
        "2025-08-01": 0,
        "2025-08-02": 0,
        "2025-08-03": null
      }
    }
  ],
  "date_range": {
    "from": "2025-08-01",
    "to": "2025-08-03"
  }
}

Struktura odpowiedzi V2:

{
  "site": {
    "id": 12,
    "url": "example.pl",
    "engine": "Google.pl [Polska]",
    "category": {
      "id": 5,
      "name": "Sklepy"
    }
  },
  "keywords": [
    {
      "id": 101,
      "keyword": "przykładowa fraza",
      "forced_location": "Warszawa",
      "is_paused": false,
      "is_hidden": false,
      "category": {
        "id": 3,
        "name": "Brand"
      },
      "positions_by_date": {
        "2025-08-01": { "position": 12, "url": "https://example.pl/oferta" },
        "2025-08-02": null,
        "2025-08-03": { "position": 10, "url": "https://example.pl/oferta" }
      }
    },
    {
      "id": 102,
      "keyword": "inna fraza",
      "forced_location": null,
      "is_paused": true,
      "is_hidden": false,
      "category": null,
      "positions_by_date": {
        "2025-08-01": { "position": 0, "url": null },
        "2025-08-02": { "position": 0, "url": null }
        "2025-08-03": null,
      }
    }
  ],
  "date_range": {
    "from": "2025-08-01",
    "to": "2025-08-03"
  }
}

site: informacje o stronie (jak w get_sites) + kategoria lub null
keywords: lista fraz ze statusem i kategorią
forced_location: nazwa lokalizacji lub null
is_paused: czy fraza jest wstrzymana
is_hidden: czy fraza jest ukryta (dla klienta)
category: obiekt { id, name } lub null
positions_by_date:
- V1: mapa data → pozycja (liczba) lub null (brak rekordu danego dnia)
- V2: mapa data → { position, url } lub null
date_range: zakres dat użyty do budowy odpowiedzi

Uwaga:
Pozycja 0 oznacza “nie znaleziono w sprawdzanym zakresie” (zgodnie z logiką aplikacji), natomiast null oznacza “brak zapisu w bazie dla tej daty” (sprawdzanie pozycji nie było wykonane).

3) Rozliczenia strony w wybranym zakresie dat

Endpoint: endpoint=get_site_billing
Metoda: GET
Parametry (wymagane):
site_id (int) — ID strony
date_from (string) — data początkowa YYYY-MM-DD
date_to (string) — data końcowa YYYY-MM-DD
Przykładowy URL:
https://adres-do-panelu.domena.pl/api.php?endpoint=get_site_billing&site_id=12&date_from=2025-01-01&date_to=2025-01-31&api_key=...

Struktura odpowiedzi:

{
  "site": {
    "id": 12,
    "url": "example.com",
    "projectName": "Example",
    "engine": "Google (Polska, polski)",
    "category": {
      "id": 5,
      "name": "Sklepy"
    },
    "currency": "PLN",
    "monthly_cost": 100.00
  },
  "date_range": {
    "from": "2025-01-01",
    "to": "2025-01-31"
  },
  "billing": {
    "rate_type": "monthly",
    "days_in_range": 31,
    "start_payment": "2024-06-01",
    "contract_end": null,
    "max_check": 100,
    "keywords": [
      {
        "id": 101,
        "keyword": "przykładowa fraza",
        "payment_method": "standard",
        "is_paused": false,
        "is_hidden": false,
        "category": {
          "id": 3,
          "name": "Brand"
        },
        "payment_ranges": [
          {
            "position_from": 1,
            "position_to": 3,
            "rate": 100.00,
            "rate_daily": 3.23,
            "days_in_range": 20,
            "amount": 64.60
          }
        ],
        "average_position": null,
        "last_day_position": null,
        "total_amount": 64.60
      }
    ],
    "summary": {
      "keywords_total": 1250.00,
      "monthly_cost": 100.00
    }
  }
}

Opis pól:

site: informacje o stronie (jak w get_sites) + currency oraz skonfigurowany abonament monthly_cost
billing.rate_type: daily lub monthly — sposób definiowania stawek w panelu
billing.days_in_range: liczba dni w żądanym zakresie (włącznie z datą początkową i końcową)
billing.start_payment / billing.contract_end: okres rozliczeniowy użytkownika przypisanego do strony (lub null)
billing.max_check: maksymalna sprawdzana pozycja dla strony
billing.keywords: lista fraz z zakresami płatności i obliczonymi kwotami
payment_method: standard (dzienna pozycja), average (pozycja średnia), last_day (pozycja z ostatniego dnia zakresu)
payment_ranges: skonfigurowane zakresy pozycji ze stawką (rate), stawką dzienną (rate_daily), liczbą dni w zakresie (days_in_range) oraz naliczoną kwotą (amount)
average_position: uzupełniane dla metody average
last_day_position: uzupełniane dla metody last_day (pozycja z dnia date_to)
total_amount: suma kwot z payment_ranges dla danej frazy
billing.summary.keywords_total: łączna kwota za frazy w żądanym zakresie dat
billing.summary.monthly_cost: skonfigurowany abonament miesięczny strony (informacyjnie; nie jest przeliczany proporcjonalnie do długości zakresu)

Uwagi:
Kwoty zwracane są jako liczby (JSON number), nie jako sformatowane teksty.
Frazy ukryte (is_hidden: true) są uwzględniane w odpowiedzi.

Zmiany i kompatybilność

Nowe endpointy są dodawane w sposób wstecznie kompatybilny.
W przyszłości mogą pojawić się kolejne rozszerzenia (np. filtrowanie, paginacja).

Jeżeli potrzebujesz dodatkowych danych w odpowiedziach lub nowych endpointów – daj znać, rozszerzymy API.