Dane rankingu (`getRankingData`)

POST/api/visibility_analysis/tools/domains_ranking/getRankingData

Zwraca globalny ranking domen według widoczności w wynikach wyszukiwania — obejmuje całą bazę kraju (dla Polski ponad 13,6 mln domen, count: 13608048 przy match_mode: "main_domain"). Ranking można zawęzić do wybranych kategorii tematycznych (categories_ranking) albo sfokusować na konkretnej domenie (domain). Wynik jest stronicowany.

Podgląd · 6 z 26 kolumn

Domena	Kategoria	Udział	Ranking · bieżący	Ranking · poprz.	Ranking · zmiana
facebook.com	Main Ranking	1	1	1	0
youtube.com	Main Ranking	1	2	2	0

match_mode: main_domain, limit: 2 — czoło globalnego rankingu domen dla Polski. Wszystkie adresowalne pola wiersza (brak pól o zmiennych kluczach). Uwaga: w visibility i top10 pola current/previous to duplikaty (aliasy) recent_value/older_value.

Zwalidowany błąd API: wywołanie bez match_mode i bez categories_ranking (np. samo {"limit": 2}) kończy się HTTP 400 z surową stroną HTML błędu (nieobsłużony wyjątek), a nie JSON-ową kopertą {"success": false, ...}. W praktyce zawsze podawaj match_mode: "main_domain" (ranking główny) albo categories_ranking: [<id>] (ranking w obrębie kategorii).

Żądanie

POST /api/visibility_analysis/tools/domains_ranking/getRankingData

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

Struktura żądania

Podstawowy

żądanie-podstawowe.jsonc


{
  "match_mode": "main_domain",
  "limit": 2
}

Rozszerzony

żądanie-rozszerzone.jsonc


{
  // ranking w obrębie kategorii zamiast rankingu głównego
  "categories_ranking": [1],
  "limit": 2,
  "page": 1
}

cURL


curl --location --request POST 'https://api.senuto.com/api/visibility_analysis/tools/domains_ranking/getRankingData' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_TOKEN_HERE' \
  --data-raw '{ "match_mode": "main_domain", "limit": 2 }'

Parametry

Name	Type	Default
`match_mode`	`"main_domain" \| "domain" \| "subdomains"` Tryb dopasowania domen w rankingu głównym (klasa `MatchMode`): `"main_domain"` — domeny główne, `"domain"` — domeny, `"subdomains"` — subdomeny. Uwaga: żądanie bez `match_mode` i bez `categories_ranking` kończy się `HTTP 400` z surową stroną HTML błędu (nieobsłużony wyjątek) — podaj jedno z tych pól.
`categories_ranking`	`number[]` Tablica id kategorii — zamiast rankingu głównego zwracany jest ranking domen w obrębie wskazanych kategorii (pole `category` w wierszach przyjmuje nazwę kategorii, np. `"Sztuka i rozrywka"` dla `[1]`). Nazwę odpowiadającą podanemu id zwraca pole `category` w wierszach odpowiedzi.
`domain`	`string` Opcjonalna domena — fokus rankingu na wskazanej domenie.
`order`	`unknown` Sortowanie wyników. Kształt parametru nie został jeszcze zweryfikowany na żywo (kontroler przekazuje go wprost do komponentu) — zostanie doprecyzowany.
`country_id`	`number` ID kraju bazy Senuto.	`1 (Polska)`
`limit`	`number` Rozmiar strony paginacji. Odbija się w `pagination.limit`.	`10`
`page`	`number` Numer strony paginacji. Paginacja działa na całej bazie (`count: 13608048` przy `match_mode: "main_domain"`).	`1`

Endpoint obsługuje metodę POST z parametrami w ciele żądania (JSON). Endpoint nie waliduje nazw pól — parametry są czytane wprost z ciała żądania, więc literówki w nazwach pól nie zwrócą błędu walidacji, tylko zostaną po cichu zignorowane. country_id jest opcjonalne (domyślnie Polska, country_id = 1).

Odpowiedź

Po pomyślnym żądaniu otrzymujesz data (tablicę wierszy rankingu) oraz pagination. Każdy wiersz opisuje jedną domenę: pole category przyjmuje wartość "Main Ranking" dla rankingu głównego albo nazwę kategorii (np. "Sztuka i rozrywka" przy categories_ranking: [1] — ranking otwiera wtedy youtube.com). Statystyki obejmują pozycję w rankingu (rank, domain_rank), widoczność (visibility) i liczbę fraz w TOP10 (top10), każdorazowo z wartością bieżącą, poprzednią, różnicą i zmianą procentową. Wiersz zawiera też listy technologii wykrytych na domenie.

Skrócona

przykładowa-odpowiedź (skrócona)


{
  "success": true,
  "data": [
    {
      "domain": "facebook.com",
      "category": "Main Ranking",
      "share": 1,
      "statistics": {
        "rank": { "recent_value": 1, "older_value": 1, "diff": 0, "percent": 0 },
        "visibility": { "recent_value": 354010944, "older_value": 355756117.4, "diff": -1745173.4, "percent": -0.0049, "current": 354010944, "previous": 355756117.4 },
        "top10": { "recent_value": 4633561, "older_value": 4628947, "diff": 4614, "percent": 0.001, "current": 4633561, "previous": 4628947 },
        "domain_rank": { "current": 1, "previous": 1, "diff": 0, "percent": 0 }
      },
      "technologies": ["ActiveCampaign", "HSTS", "HTTP/3"],
      "technologies_new": [],
      "technologies_groups": ["Email", "Marketing automation", "Miscellaneous", "Security"]
    }
  ],
  "pagination": { "page_count": 6804024, "current_page": 1, "has_next_page": true, "has_prev_page": false, "count": 13608048, "limit": 2 }
}

Pełna

przykładowa-odpowiedź (200)


{
  "success": true,
  "data": [
    {
      "domain": "facebook.com",
      "category": "Main Ranking",
      "share": 1,
      "statistics": {
        "rank": {
          "recent_value": 1,
          "older_value": 1,
          "diff": 0,
          "percent": 0
        },
        "visibility": {
          "recent_value": 354010944,
          "older_value": 355756117.4,
          "diff": -1745173.4,
          "percent": -0.0049,
          "current": 354010944,
          "previous": 355756117.4
        },
        "top10": {
          "recent_value": 4633561,
          "older_value": 4628947,
          "diff": 4614,
          "percent": 0.001,
          "current": 4633561,
          "previous": 4628947
        },
        "domain_rank": {
          "current": 1,
          "previous": 1,
          "diff": 0,
          "percent": 0
        }
      },
      "technologies": ["ActiveCampaign", "HSTS", "HTTP/3"],
      "technologies_new": [],
      "technologies_groups": ["Email", "Marketing automation", "Miscellaneous", "Security"]
    },
    {
      "domain": "youtube.com",
      "category": "Main Ranking",
      "share": 1,
      "statistics": {
        "rank": {
          "recent_value": 2,
          "older_value": 2,
          "diff": 0,
          "percent": 0
        },
        "visibility": {
          "recent_value": 342211072,
          "older_value": 342656302.28,
          "diff": -445230.28,
          "percent": -0.0013,
          "current": 342211072,
          "previous": 342656302.28
        },
        "top10": {
          "recent_value": 4783588,
          "older_value": 4776688,
          "diff": 6900,
          "percent": 0.0014,
          "current": 4783588,
          "previous": 4776688
        },
        "domain_rank": {
          "current": 2,
          "previous": 2,
          "diff": 0,
          "percent": 0
        }
      },
      "technologies": ["ActiveCampaign", "HSTS", "HTTP/3"],
      "technologies_new": [],
      "technologies_groups": ["Email", "Marketing automation", "Miscellaneous", "Security"]
    }
  ],
  "pagination": {
    "page_count": 6804024,
    "current_page": 1,
    "has_next_page": true,
    "has_prev_page": false,
    "count": 13608048,
    "limit": 2
  }
}

Struktura odpowiedzi

Name	Type	Default
`success`	`boolean` `true` przy powodzeniu; przy błędzie `false` i koperta z `error`
`data`	`RankingRow[]` Wiersze rankingu domen
`pagination`	`{ page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; count: number; limit: number; }` Metadane paginacji

Błędy

Żądanie bez match_mode i bez categories_ranking (np. samo {"limit": 2}) zwraca HTTP 400 z surową stroną HTML (nieobsłużony wyjątek serwera) — odpowiedź nie jest JSON-em, więc parser JSON po stronie klienta rzuci własny błąd. Zabezpiecz integrację: sprawdzaj Content-Type odpowiedzi i zawsze przekazuj match_mode albo categories_ranking.

Kontroler nie ma walidatora pól, więc nie zwraca typowej JSON-owej koperty invalid_data — nieznane lub błędnie nazwane pola są ignorowane, a brak pól wymaganych funkcjonalnie kończy się opisanym wyżej 400 z HTML-em.

Powiązane akcje

Analiza widoczności — przegląd modułu — pozostałe raporty widoczności domeny.

Dane rankingu (getRankingData)