Snippety SERP: statystyki (getStatistics)
/api/rank_tracker/reports/snippets/getStatisticsZwraca statystyki elementów SERP (snippetów) wykrytych dla fraz projektu Rank Tracker. Dla każdego typu snippetu akcja porównuje dwa snapshoty — date_min (wartości previous) i date_max (wartości recent) — i raportuje, ile fraz projektu ma dany snippet w SERP (all_keywords) oraz w ilu z nich widoczna jest domena projektu (visible_keywords), wraz z różnicami bezwzględnymi i procentowymi oraz procentowym pokryciem SERP (serp_coverage).
Powyższy przykład w playgroundzie został skrócony do 4 typów snippetów dla czytelności — pełną, zwalidowaną odpowiedź (14 typów) znajdziesz niżej w sekcji „Odpowiedź”.
Żądanie
POST /api/rank_tracker/reports/snippets/getStatistics
Nagłówki: Authorization: Bearer <token>, Content-Type: application/json.
Struktura żądania
Podstawowy
{
"project_id": null,
"date_min": "2026-06-20",
"date_max": "2026-06-29"
}Parametry
| Name | Type | Default |
|---|---|---|
project_id | numberWymagane. ID projektu Rank Tracker (walidator | |
date_min | stringWymagane. Data początkowa zakresu w formacie | |
date_max | stringWymagane. Data końcowa zakresu w formacie |
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 typ snippetu (klucze dynamiczne, np. image_thumbs, wiki_right), a nie tablica — iteruj po kluczach, nie po indeksach. (2) serp_coverage to string (np. "29.79" = procent pokrycia SERP), nie liczba. (3) diff_percent bywa liczbą 0 albo stringiem (np. "-24.32") — parsuj defensywnie. (4) Odpowiedź nie ma paginacji. (5) Zbiór typów snippetów w odpowiedzi może być podzbiorem wszystkich typów — siostrzana akcja getHistory dla tego samego projektu zwróciła dodatkowo m.in. people_also_ask, related_searches, video_thumbs, videos_pack, featured_snippets i answer_box; zbiór kluczy traktuj jako dynamiczny.
Odpowiedź
Po pomyślnym żądaniu otrzymujesz data — obiekt, którego kluczami są typy snippetów. Każdy wpis zawiera serp_coverage (string z procentem pokrycia SERP), powtórzoną nazwę typu w polu snippet oraz dwa bloki liczników: all_keywords (frazy projektu z danym snippetem w SERP) i visible_keywords (frazy, w których snippecie widoczna jest domena projektu). Każdy blok liczników ma recent (stan z date_max), previous (stan z date_min), diff oraz diff_percent.
Skrócona
{
"success": true,
"data": {
"image_thumbs": {
"serp_coverage": "29.79",
"snippet": "image_thumbs",
"all_keywords": { "recent": 28, "previous": 37, "diff": -9, "diff_percent": "-24.32" },
"visible_keywords": { "recent": 0, "previous": 0, "diff": 0, "diff_percent": 0 }
},
"wiki_right": {
"serp_coverage": "12.77",
"snippet": "wiki_right",
"all_keywords": { "recent": 12, "previous": 9, "diff": 3, "diff_percent": "33.33" },
"visible_keywords": { "recent": 0, "previous": 0, "diff": 0, "diff_percent": 0 }
}
}
}Struktura odpowiedzi
| Name | Type | Default |
|---|---|---|
success | boolean
| |
data | Record<string, SnippetStatistics>Obiekt keyed by typ snippetu (klucze dynamiczne, np. |
Błędy
| Name | Type | Default |
|---|---|---|
success | false | |
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
getStatistics— porównanie dwóch snapshotów per typ snippetu, z pokryciem SERP i widocznością domeny (ta strona)getHistory— liczba fraz z danym typem snippetu w SERP, per data pomiaru (POST,project_id+date_min+date_max)