--- title: "Dane rankingu (`getRankingData`)" source: https://docs.senuto.com/modules/visibility_analysis/va-domains-ranking-getRankingData api: POST /api/visibility_analysis/tools/domains_ranking/getRankingData --- # 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. | Domena | Kategoria | Udział | Ranking · bieżący | Ranking · poprz. | Ranking · zmiana | Ranking · % | Widoczność · bieżąca | Widoczność · poprz. | Widoczność · zmiana | Widoczność · % | Widoczność · current (alias) | Widoczność · previous (alias) | TOP10 · bieżąca | TOP10 · poprz. | TOP10 · zmiana | TOP10 · % | TOP10 · current (alias) | TOP10 · previous (alias) | Ranga domeny · bieżąca | Ranga domeny · poprz. | Ranga domeny · zmiana | Ranga domeny · % | Technologie | Nowe technologie | Grupy technologii | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | facebook.com | Main Ranking | 1 | 1 | 1 | 0 | 0 | 354010944 | 355756117.4 | -1745173.4 | -0.0049 | 354010944 | 355756117.4 | 4633561 | 4628947 | 4614 | 0.001 | 4633561 | 4628947 | 1 | 1 | 0 | 0 | ["ActiveCampaign","HSTS","HTTP/3"] | [] | ["Email","Marketing automation","Miscellaneous","Security"] | | youtube.com | Main Ranking | 1 | 2 | 2 | 0 | 0 | 342211072 | 342656302.28 | -445230.28 | -0.0013 | 342211072 | 342656302.28 | 4783588 | 4776688 | 6900 | 0.0014 | 4783588 | 4776688 | 2 | 2 | 0 | 0 | ["ActiveCampaign","HSTS","HTTP/3"] | [] | ["Email","Marketing automation","Miscellaneous","Security"] | _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`._ > **Błąd:** > **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: []` (ranking w obrębie kategorii). --- ## Żądanie `POST` `/api/visibility_analysis/tools/domains_ranking/getRankingData` Nagłówki: `Authorization: Bearer `, `Content-Type: application/json`. ### Struktura żądania **Podstawowy** ```jsonc filename="żądanie-podstawowe.jsonc" { "match_mode": "main_domain", "limit": 2 } ``` **Rozszerzony** ```jsonc filename="żądanie-rozszerzone.jsonc" { // ranking w obrębie kategorii zamiast rankingu głównego "categories_ranking": [1], "limit": 2, "page": 1 } ``` **cURL** ```bash 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 ```ts type GetRankingDataRequest = { /** * 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. */ match_mode?: "main_domain" | "domain" | "subdomains"; /** * 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. */ categories_ranking?: number[]; /** * Opcjonalna domena — fokus rankingu na wskazanej domenie. */ domain?: string; /** * Sortowanie wyników. Kształt parametru nie został jeszcze zweryfikowany na żywo * (kontroler przekazuje go wprost do komponentu) — zostanie doprecyzowany. */ order?: unknown; /** * ID kraju bazy Senuto. * @default 1 (Polska) */ country_id?: number; /** * Rozmiar strony paginacji. Odbija się w `pagination.limit`. * @default 10 */ limit?: number; /** * Numer strony paginacji. Paginacja działa na całej bazie * (`count: 13608048` przy `match_mode: "main_domain"`). * @default 1 */ page?: number; } export default GetRankingDataRequest ``` > **Ostrzeżenie:** > 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** ```json filename="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** ```json filename="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 ```ts type GetRankingDataResponse = { /** `true` przy powodzeniu; przy błędzie `false` i koperta z `error` */ success: boolean; /** Wiersze rankingu domen */ data: RankingRow[]; /** Metadane paginacji */ pagination: { page_count: number; current_page: number; has_next_page: boolean; has_prev_page: boolean; /** Łączna liczba domen w rankingu (13 608 048 przy `match_mode: "main_domain"`) */ count: number; limit: number; }; } type RankingRow = { /** Nazwa domeny */ domain: string; /** `"Main Ranking"` dla rankingu głównego albo nazwa kategorii (np. `"Sztuka i rozrywka"`) przy `categories_ranking` */ category: string; share: number; statistics: { /** Pozycja w rankingu (bieżąca vs poprzednia) */ rank: StatDiff; /** Widoczność domeny. **Uwaga:** `current`/`previous` to duplikaty (aliasy) `recent_value`/`older_value` */ visibility: StatDiff & { current: number; previous: number }; /** Liczba fraz w TOP10. **Uwaga:** `current`/`previous` to duplikaty (aliasy) `recent_value`/`older_value` */ top10: StatDiff & { current: number; previous: number }; /** Pozycja rankingowa domeny */ domain_rank: { current: number; previous: number; diff: number; percent: number }; }; /** Technologie wykryte na domenie */ technologies: string[]; /** Nowo wykryte technologie */ technologies_new: string[]; /** Grupy technologii */ technologies_groups: string[]; } type StatDiff = { /** Wartość bieżąca */ recent_value: number; /** Wartość poprzednia */ older_value: number; /** Różnica bieżąca − poprzednia */ diff: number; /** Zmiana procentowa (ułamek, np. `-0.0049`) */ percent: number; } export default GetRankingDataResponse ``` ## Błędy > **Błąd:** > Żą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](/modules/visibility_analysis) — pozostałe raporty widoczności domeny.