Dashboard: statystyki domeny (`getDomainStatistics`)

GET/api/visibility_analysis/reports/dashboard/getDomainStatistics

Zwraca kluczowe metryki widoczności dla domeny (TOP3 / TOP10, widoczność całkowita, ranking domeny, wartość ekwiwalentu reklamowego, wiodąca kategoria oraz słowa kluczowe AI Overviews), każdą jako porównanie ostatniego okresu z poprzednim.

Żądanie

GET /api/visibility_analysis/reports/dashboard/getDomainStatistics

Parametry są odczytywane z query string (getQuery). Nagłówki: Authorization: Bearer <token>.

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


// Query string parameters
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain"
}
// GET /api/visibility_analysis/reports/dashboard/getDomainStatistics?domain=zalando.pl&fetch_mode=topLevelDomain

Rozszerzony

żądanie-rozszerzone.jsonc


// Query string parameters
{
  "domain": "zalando.pl",
  "fetch_mode": "topLevelDomain",
  "country_id": 1
}
// GET /api/visibility_analysis/reports/dashboard/getDomainStatistics?domain=zalando.pl&fetch_mode=topLevelDomain&country_id=1

cURL


curl --location --request GET 'https://api.senuto.com/api/visibility_analysis/reports/dashboard/getDomainStatistics?domain=zalando.pl&fetch_mode=topLevelDomain' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE'

Parametry

Name	Type	Default
`domain`	`string` Wymagane. Domena lub subdomena do analizy, walidowana po stronie API. Bez schematu/protokołu — np. `zalando.pl`.
`fetch_mode`	`"topLevelDomain" \| "subdomain" \| "catalog" \| "url"` Wymagane. Tryb agregacji danych o widoczności. Uwaga: `domain` NIE jest prawidłową wartością — dla całej domeny użyj `topLevelDomain`. `topLevelDomain` — cała domena (typowy przypadek) `subdomain` — pojedyncza subdomena `catalog` — ścieżka/katalog `url` — dokładny adres URL
`country_id`	`number` Identyfikator kraju (baza Google). Opcjonalne — gdy jest pominięte, `0` lub nieprawidłowe, backend stosuje domyślny kraj (PL).	`1`

Dozwolone wartości fetch_mode to dokładnie ['topLevelDomain', 'subdomain', 'catalog', 'url'] (DataFetchMode::AVAILABLE_MODES). Przekazanie domain to częsty błąd — nie odpowiada żadnemu trybowi i nie przechodzi walidacji.

Ta akcja odczytuje dane z query string (kontroler używa getQuery), więc parametry przesyłaj w adresie URL — wysłanie ich wyłącznie w treści JSON zwraca 418. Zarówno domain, jak i fetch_mode są wymagane. Wartość fetch_mode domain nie istnieje — dla całej domeny użyj topLevelDomain. country_id jest opcjonalne i domyślnie przyjmuje PL (1), gdy jest pominięte lub nieprawidłowe.

Odpowiedź

W przypadku powodzenia otrzymujesz data.statistics — pojedynczy obiekt zawierający 9 metryk. Każda metryka to porównanie recent_value z older_value (bieżący okres vs poprzedni) wraz z bezwzględną różnicą diff oraz ułamkowym percent (np. -0.0011 = -0.11%). Nie ma paginacji — to obiekt statystyk, a nie lista. category jest zagnieżdżona jako { name, statistics }.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": {
    "statistics": {
      "visibility": { "recent_value": 5423828, "older_value": 5433671, "diff": -9843, "percent": -0.0018 },
      "top3": { "recent_value": 46546, "older_value": 46595, "diff": -49, "percent": -0.0011 }
      /* … top10, domain_rank, ads_equivalent, category, aio_keywords, aio_visible_keywords */
    }
  }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`{ statistics: { top3: Metric; top10: Metric; visibility: Metric; domain_rank: Metric; ads_equivalent: Metric; category: { name: string; statistics: Metric; }; aio_keywords: Metric; aio_visible_keywords: Metric; }; }`

Błędy

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

418 jest zwracane także dla błędów walidacji — nie tylko przy ograniczaniu liczby żądań. Najczęstsze przyczyny to przesłanie parametrów w treści JSON zamiast w query string (przez co getQuery jest puste) oraz pominięcie fetch_mode. Brakujące fetch_mode → {"success":false,"data":{"error":{"type":"invalid_data","params":{"fetch_mode":{"_required":"This field is required"}}}}}.

Powiązane akcje

getDomainStatistics — kluczowe statystyki domeny (ta strona)
getData (Positions) — pozycje na poziomie słów kluczowych, stojące za tymi zagregowanymi danymi (ten sam kształt domain + fetch_mode)
getDomainStatistics dla innego fetch_mode — przekaż subdomain, catalog lub url, aby ograniczyć te same metryki do subdomeny, ścieżki lub dokładnego adresu URL

Dashboard: statystyki domeny (getDomainStatistics)