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 <token>, Content-Type: application/json.

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


// endpoint nie przyjmuje żadnych parametrów — wyślij puste ciało
{}

Rozszerzony

żądanie-rozszerzone.jsonc


// brak wariantu rozszerzonego — nie istnieją parametry opcjonalne;
// zakres (ostatnie 30 dni) jest ustalany po stronie serwera
{}

cURL


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).

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

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 }
    }
  }
}

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

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`{ history: { positions: Record<string, number>; positions_diff: Record<string, number>; wins: Record<string, number>; lost: Record<string, number>; wins_lost: Record<...>; visibility: Record<...>; visibility_diff: Record<...>; }; statistics: { ...; }; projects: { ...; }; }`

Błędy

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

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)

Pozycje: średnie konta (getAvgData)