Frazy: zrzut SERP (`getSerpHtml`)

POST/api/rank_tracker/reports/keywords/getSerpHtml

Zwraca zapisany zrzut HTML strony wyników Google (SERP) dla wskazanej frazy projektu Rank Tracker z danego dnia. Odpowiedź zawiera pojedyncze pole data.html — pełny kod HTML strony wyników albo null, jeśli zrzut dla danej frazy i daty nie jest przechowywany.

Żądanie

POST /api/rank_tracker/reports/keywords/getSerpHtml

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

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "project_id": null,
  "keyword_id": null,
  "date": "2026-07-01"
}

Parametry

Name	Type	Default
`project_id`	`number` Wymagane. ID projektu Rank Tracker (walidator `SerpHtmlValidator`). Realny `project_id` pobierzesz z `POST /api/rank_tracker/management/projects/getMyActiveProjects`.
`keyword_id`	`number` Wymagane. ID frazy w projekcie. Identyfikatory fraz pobierzesz np. z akcji `getProjectKeywords` lub `getGroupKeywords` w tym samym kontrolerze. Realny `keyword_id` pobierzesz z `POST /api/rank_tracker/reports/keywords/getData`.
`date`	`string` Wymagane. Dzień, z którego chcesz pobrać zrzut SERP, w formacie `YYYY-MM-DD`. Głębokość historii ogranicza limit planu `monitoring_serp_html_history_limit` — data spoza limitu skutkuje `418`.

Poza walidacją pól (SerpHtmlValidator wymaga project_id, keyword_id oraz date w formacie YYYY-MM-DD) działa tu limit planu monitoring_serp_html_history_limit — określa on głębokość historii zrzutów, do której możesz sięgać. Żądanie daty spoza dozwolonej głębokości historii kończy się błędem 418. Data mieszcząca się w limicie, ale bez zapisanego zrzutu, zwraca HTTP 200 z html: null — brak zrzutu nie jest sygnalizowany błędem.

Odpowiedź

Po pomyślnym żądaniu otrzymujesz data.html — kod HTML strony wyników Google zapisany dla frazy w podanym dniu, albo null, gdy zrzut nie jest przechowywany (np. plan bez historii zrzutów SERP lub brak zapisu z tego dnia).

Pełna (zwalidowana)

przykładowa-odpowiedź (200)


{
  "success": true,
  "data": {
    "html": null
  }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`{ html: string \| null; }`

Błędy

Name	Type	Default
`success`	`false`
`data`	`{ error: { type: string; message: string; params?: Record<string, Record<string, string>>; }; }`

Brak któregokolwiek z wymaganych pól (project_id, keyword_id, date) lub niepoprawny format daty skutkuje błędem walidacji invalid_data (418). Kod 418 zwracany jest także przy przekroczeniu głębokości historii zrzutów wyznaczonej przez limit planu monitoring_serp_html_history_limit. Brak zapisanego zrzutu dla poprawnej daty nie jest błędem — otrzymasz HTTP 200 z html: null.

Powiązane akcje

getProjectKeywords — słowa kluczowe całego projektu (POST, project_id)
getGroupKeywords — lekka lista (id + keyword) ograniczona do jednej grupy
getData — pełne statystyki pozycji (POST, project_id + group_id + filtering + order)
getSerpHtml — zapis HTML wyników SERP dla frazy i dnia (ta strona)
getBestKeywords / getProjectsStatus — pozostałe akcje pomocnicze kontrolera

Frazy: zrzut SERP (getSerpHtml)