Skip to Content
ModułyMonitoringHistoria

Snippety SERP: historia (getHistory)

POST/api/rank_tracker/reports/snippets/getHistory

Zwraca historię elementów SERP (snippetów) wykrytych dla fraz projektu Rank Tracker: dla każdej daty pomiaru z zakresu date_min–date_max raportowana jest liczba fraz projektu, dla których dany typ snippetu występuje w SERP. Wynik pozwala śledzić, jak zmienia się obecność poszczególnych typów snippetów (np. people_also_ask, image_thumbs, featured_snippets) w czasie.

Żądanie

POST /api/rank_tracker/reports/snippets/getHistory

Nagłówki: Authorization: Bearer <token>, Content-Type: application/json.

Struktura żądania

żądanie-podstawowe.jsonc
{
  "project_id": null,
  "date_min": "2026-06-20",
  "date_max": "2026-06-29"
}

Parametry

NameTypeDefault
project_idnumber

Wymagane. ID projektu Rank Tracker (walidator SnippetsValidator). Musi należeć do użytkownika, inaczej zwracane jest 418 z komunikatem Unauthorized access. Realny project_id pobierzesz z POST /api/rank_tracker/management/projects/getMyActiveProjects.

date_minstring

Wymagane. Data początkowa zakresu w formacie YYYY-MM-DD.

date_maxstring

Wymagane. Data końcowa zakresu w formacie YYYY-MM-DD.

Znany bug walidacji: gdy date_min jest późniejsze niż date_max, reguły DateRangeRules zwracają błąd z odwróconym komunikatem (treść sugeruje odwrotny kierunek naruszenia). Pilnuj poprawnej kolejności dat po swojej stronie.

Pułapki tego endpointu: (1) data to obiekt keyed by daty pomiaru (YYYY-MM-DD) — w zwalidowanej odpowiedzi znalazły się dokładnie dwa snapshoty, date_max i date_min (w tej kolejności), ale kolejności kluczy nie traktuj jako gwarantowanej. (2) Każdy snapshot to mapa typ snippetu → liczba fraz (klucze dynamiczne). (3) Zbiór typów snippetów może się różnić między datami — np. snapshot 2026-06-20 nie zawiera kluczy featured_snippets ani answer_box, które występują w 2026-06-29; brakującego klucza nie interpretuj automatycznie jako zera bez własnej decyzji. (4) Odpowiedź nie ma paginacji.

Odpowiedź

Po pomyślnym żądaniu otrzymujesz data — obiekt keyed by daty pomiaru. Każdy snapshot to mapa: typ snippetu → liczba fraz projektu, dla których ten snippet występował w SERP w danym dniu. Zwróć uwagę, że listy typów mogą się różnić między datami (poniżej 2026-06-20 nie ma featured_snippets ani answer_box).

przykładowa-odpowiedź (skrócona)
{
  "success": true,
  "data": {
    "2026-06-29": {
      "image_thumbs": 28,
      "people_also_ask": 83,
      "related_searches": 94,
      "featured_snippets": 4
    },
    "2026-06-20": {
      "image_thumbs": 37,
      "people_also_ask": 71,
      "related_searches": 89
    }
  }
}

Struktura odpowiedzi

NameTypeDefault
successboolean

true przy powodzeniu; przy błędzie false i koperta z error

dataRecord<string, SnippetHistorySnapshot>

Obiekt keyed by data pomiaru (YYYY-MM-DD). To NIE jest tablica i NIE ma paginacji. Kolejność kluczy nie jest gwarantowana.

Błędy

NameTypeDefault
successfalse
data{ error: { type: string; message: string; params?: Record<string, Record<string, string>>; }; }

Błędy walidacji zwracane są ze statusem 418. Brak któregokolwiek z pól project_id, date_min, date_max → invalid_data. project_id nienależący do użytkownika → Unauthorized access (418), a nie 404. Znany bug: przy date_min późniejszym niż date_max komunikat błędu z DateRangeRules jest odwrócony względem faktycznego naruszenia.

Powiązane akcje

  • getHistory — liczba fraz z danym typem snippetu w SERP, per data pomiaru (ta strona)
  • getStatistics — porównanie dwóch snapshotów per typ snippetu, z pokryciem SERP (serp_coverage) i widocznością domeny (POST, project_id + date_min + date_max)
Ostatnia aktualizacja:
StatystykiStatystyki