--- title: "Pozycje: średnie konta (`getAvgData`)" source: https://docs.senuto.com/modules/rank_tracker/rt-positions-getAvgData api: POST /api/rank_tracker/reports/positions/getAvgData --- # Pozycje: średnie konta (`getAvgData`) **`POST /api/rank_tracker/reports/positions/getAvgData`** Zwraca zagregowane średnie pozycji i widoczności **dla całego konta użytkownika** — endpoint działa na poziomie użytkownika i sumuje dane ze wszystkich jego projektów Rank Tracker. Odpowiedź zawiera trzy sekcje: `history` (dzienne szeregi czasowe z ostatnich 30 dni — pozycje, wzrosty, spadki, widoczność), `statistics` (statystyki zbiorcze i porównania okres do okresu) oraz `projects` (liczba projektów, bilans projektów rosnących/spadających i łączna liczba monitorowanych fraz). --- ## Żądanie `POST` `/api/rank_tracker/reports/positions/getAvgData` Nagłówki: `Authorization: Bearer `, `Content-Type: application/json`. ### Struktura żądania **Podstawowy** ```jsonc filename="żądanie-podstawowe.jsonc" // endpoint nie przyjmuje żadnych parametrów — wyślij puste ciało {} ``` **Rozszerzony** ```jsonc filename="żądanie-rozszerzone.jsonc" // brak wariantu rozszerzonego — nie istnieją parametry opcjonalne; // zakres (ostatnie 30 dni) jest ustalany po stronie serwera {} ``` **cURL** ```bash curl --location --request POST 'https://api.senuto.com/api/rank_tracker/reports/positions/getAvgData' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \ --data-raw '{}' ``` ### Parametry Endpoint nie przyjmuje żadnych parametrów — wyślij puste ciało `{}`. Zakres kont i projektów wynika wyłącznie z tokenu `Authorization`: agregowane są wszystkie projekty zalogowanego użytkownika, a okres jest stały (ostatnie 30 dni, ustalany po stronie serwera). > **Ostrzeżenie:** > Endpoint przyjmuje **puste ciało żądania** (`{}`) — nie ma żadnych parametrów. Zakres danych jest **stały: ostatnie 30 dni**, ustalany po stronie serwera, i nie da się go zmienić. Nie ma też paginacji. **Pułapka:** klucze map w `history` to **uniksowe timestampy serializowane jako stringi** (np. `"1780358400"`), nie daty `YYYY-MM-DD` — przed wykreśleniem szeregów przekonwertuj je na daty. ## Odpowiedź `data` zawiera trzy sekcje. `history` to siedem map o kluczach będących **uniksowymi timestampami (stringi)** i wartościach liczbowych — po jednym punkcie na dzień, około 30 punktów na mapę. `statistics` podsumowuje okres: sumy wzrostów/spadków, średnie pozycji i widoczności oraz porównania okres do okresu (`older_value` / `recent_value` / `diff` / `percent`). `projects` opisuje portfel: liczbę projektów z rosnącą (`wins.count`) i spadającą (`lost.count`) widocznością, łączną liczbę projektów (`quantity`) i łączną liczbę monitorowanych fraz (`keywords.quantity`). **Skrócona** ```json filename="przykładowa-odpowiedź (skrócona)" { "success": true, "data": { "history": { "positions": { "1780358400": 41.61, "1782950400": 42.13 }, "visibility": { "1780358400": 353.58, "1782950400": 687.5 } }, "statistics": { "positions_avg": 41.76, "visibility_avg": 758.55 }, "projects": { "quantity": 6, "keywords": { "quantity": 752 } } } } ``` **Pełna** ```json filename="przykładowa-odpowiedź (200)" { "success": true, "data": { "history": { "positions": { "1780358400": 41.61, "1780444800": 41.83, "1782950400": 42.13 }, "positions_diff": { "1780358400": 0, "1780444800": 0.22, "1782950400": -0.22 }, "wins": { "1780358400": 3.33, "1780444800": 7.17, "1782950400": 9.33 }, "lost": { "1780358400": 10.67, "1780444800": 9.67, "1782950400": 5.33 }, "wins_lost": { "1780358400": 7, "1780444800": 8.42, "1782950400": 7.33 }, "visibility": { "1780358400": 353.58, "1780444800": 714.7, "1782950400": 687.5 }, "visibility_diff": { "1780358400": 0, "1780444800": 361.12, "1782950400": 22.76 } }, "statistics": { "wins_sum": 1486.98, "lost_sum": 1565.94, "visibility_avg": 758.55, "visibility_diff_avg": { "recent_value": 0.0147, "percent": 1.47 }, "visibility": { "older_value": 687.5, "recent_value": 664.74, "diff": -22.76, "percent": -3.3105 }, "positions_avg": 41.76, "positions_diff_avg": { "recent_value": 0.0004, "percent": 0.04 }, "positions": { "older_value": 42.13, "recent_value": 42.35, "diff": 0.22, "percent": 0.5222 } }, "projects": { "wins": { "count": 1 }, "lost": { "count": 2 }, "quantity": 6, "keywords": { "quantity": 752 } } } } ``` > **Informacja:** > Każda mapa w `history` została w powyższym przykładzie **skrócona do 3 z \~30 punktów dziennych** — realna odpowiedź zawiera po jednym wpisie na każdy dzień ostatnich 30 dni. ### Struktura odpowiedzi ```ts type GetAvgDataResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; data: { /** * Dzienne szeregi czasowe z ostatnich 30 dni. * Klucze wszystkich map to **uniksowe timestampy jako stringi** (np. `"1780358400"`). */ history: { /** Średnia pozycja konta danego dnia */ positions: Record; /** Dzienna zmiana średniej pozycji */ positions_diff: Record; /** Średnia liczba wzrostów pozycji danego dnia */ wins: Record; /** Średnia liczba spadków pozycji danego dnia */ lost: Record; /** Łączny bilans wzrostów i spadków */ wins_lost: Record; /** Widoczność konta danego dnia */ visibility: Record; /** Dzienna zmiana widoczności */ visibility_diff: Record; }; /** Statystyki zbiorcze dla okresu 30 dni */ statistics: { /** Suma wzrostów pozycji w okresie */ wins_sum: number; /** Suma spadków pozycji w okresie */ lost_sum: number; /** Średnia widoczność w okresie */ visibility_avg: number; /** Średnia zmiana widoczności */ visibility_diff_avg: { recent_value: number; percent: number; }; /** Porównanie widoczności okres do okresu */ visibility: PeriodComparison; /** Średnia pozycja w okresie */ positions_avg: number; /** Średnia zmiana pozycji */ positions_diff_avg: { recent_value: number; percent: number; }; /** Porównanie średniej pozycji okres do okresu */ positions: PeriodComparison; }; /** Podsumowanie portfela projektów konta */ projects: { /** Liczba projektów z rosnącą widocznością */ wins: { count: number }; /** Liczba projektów ze spadającą widocznością */ lost: { count: number }; /** Łączna liczba projektów użytkownika */ quantity: number; /** Łączna liczba monitorowanych fraz we wszystkich projektach */ keywords: { quantity: number }; }; }; } type PeriodComparison = { /** Wartość ze starszego punktu porównania */ older_value: number; /** Wartość z nowszego punktu porównania */ recent_value: number; /** Różnica (recent - older) */ diff: number; /** Zmiana procentowa */ percent: number; } export default GetAvgDataResponse ``` ## Błędy ```ts type ErrorResponse = { success: false; data: { error: { /** np. invalid_data, unknown */ type: string; message: string; /** pole -> reguła -> komunikat (dla invalid_data) */ params?: Record>; }; }; } export default ErrorResponse ``` > **Błąd:** > Ponieważ endpoint nie ma parametrów, praktycznie jedyne źródła błędów to uwierzytelnienie: brak lub nieprawidłowy token `Authorization: Bearer` zwraca błąd autoryzacji zamiast danych. Dane zawsze dotyczą konta z tokenu — nie da się wskazać innego użytkownika ani pojedynczego projektu. ## Powiązane akcje - `getData` — pełna, stronicowana lista pozycji projektu (warianty `/wins` i `/losses` jako segmenty URL) - `getKeywordPositions` — szczegóły pojedynczej frazy z dokładnym dopasowaniem - `getAvgData` — średnie pozycji i widoczności zagregowane dla wszystkich projektów konta (ta strona)