Dokumentacja API Stat4Seo

Przez /

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

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
  • 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=...

Struktura odpowiedzi:

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

Opis pól:

  • 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: mapa data → pozycja (liczba) lub null (brak rekordu danego dnia)
  • 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).

Zmiany i kompatybilność

W przyszłości mogą pojawić się kolejne endpointy (np. filtrowanie, paginacja).

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

Przewijanie do góry