Skip to Content
ModułyAnaliza widocznościWykres

Cechy fraz: wykres (getCharacteristicsChart)

GET/api/visibility_analysis/reports/keywords/getCharacteristicsChart

Zwraca dane do wykresu rozkładu fraz domeny według wybranej cechy (characteristics) — np. liczby słów we frazie, trendów, liczby wyszukiwań, trudności, parametrów frazy lub parametrów SERP. Wynik to tablica serii (po jednej na domenę): każda seria zawiera etykietę osi Y oraz mapę kubełek → liczba fraz. Opcjonalnie możesz dodać do 10 konkurentów, aby porównać rozkłady na tym samym wykresie.

Rozkład fraz wg długości (characteristics: words_count)
1: 7475 fraz747512: 77 199 fraz77 19923: 119 515 fraz119 51534: 62 457 fraz62 45745: 17 151 fraz17 15156: 3838 fraz383867: 981 fraz98178: 326 fraz32689: 121 fraz121910: 51 fraz5110
zalando.pl. Kubełek = liczba słów we frazie, wartość = liczba fraz o tej długości. Inne wartości `characteristics` dają inne kubełki.

Żądanie

GET /api/visibility_analysis/reports/keywords/getCharacteristicsChart

Nagłówki: Authorization: Bearer <token>. Parametry przekazywane w query stringu.

Struktura żądania

query-string.txt
/api/visibility_analysis/reports/keywords/getCharacteristicsChart
  ?domain=zalando.pl
  &fetch_mode=topLevelDomain
  &country_id=1
  &characteristics=words_count

Parametry

NameTypeDefault
domainstring

Wymagane. Domena, subdomena, katalog lub URL do analizy — interpretowane zgodnie z fetch_mode.

fetch_mode"topLevelDomain" | "subdomain" | "catalog" | "url"

Wymagane. Sposób interpretacji domain.

  • topLevelDomain — cała domena
  • subdomain — pojedyncza subdomena
  • catalog — ścieżka/katalog
  • url — dokładny URL
country_idnumber

Wymagane. Id kraju (bazy danych). Polska = 1. Nieznana wartość → 418 z komunikatem Unknown country_id.

characteristics"words_count" | "trends" | "searches" | "difficulty" | "keyword_params" | "serp_params"

Wymagane. Cecha fraz, według której budowany jest rozkład (walidator inList).

competitorsstring[]

Tablica maks. 10 domen konkurentów do porównania na tym samym wykresie. W query stringu przekazywana jako JSON, np. competitors=["allegro.pl","modivo.pl"].

Cztery parametry są wymagane: domain, fetch_mode, country_id oraz characteristics. To endpoint GET — parametry przekazujesz w query stringu, a competitors (tablicę) serializujesz jako JSON. Nieznane country_id zwraca 418 z komunikatem Unknown country_id; characteristics spoza dozwolonej listy jest odrzucane przez walidator (inList).

Odpowiedź

W przypadku powodzenia otrzymujesz data — tablicę serii, po jednej na każdą domenę (analizowaną i ewentualnych konkurentów). Każda seria zawiera domain, etykietę osi Y label_y (zwracaną po angielsku, np. "Number of keywords"), flagę is_main (czy to domena główna z żądania) oraz obiekt data z mapą kubełek → liczba fraz pod kluczem równym wybranej wartości characteristics. Endpoint nie zwraca paginacji.

przykładowa-odpowiedź (skrócona)
{
  "success": true,
  "data": [
    { "domain": "zalando.pl", "label_y": "Number of keywords", "is_main": true, "data": { "words_count": { "1": 7475, "2": 77199 /* … */ } } }
  ]
}

Struktura odpowiedzi

NameTypeDefault
successboolean

true przy powodzeniu; przy błędzie false i koperta z error

dataCharacteristicsSeries[]

Serie wykresu — po jednej na domenę (główna + ewentualni konkurenci)

Błędy

NameTypeDefault
successfalse
data{ error: { type: string; message: string; params?: Record<string, Record<string, string>>; }; }

418 zwracany jest również dla błędów walidacji — nie tylko przy ograniczeniu liczby żądań (rate limiting). Brak wymaganego pola lub nieznane country_id → odpowiedź invalid_data (dla nieznanego kraju komunikat Unknown country_id). Wartość characteristics spoza listy words_count | trends | searches | difficulty | keyword_params | serp_params jest odrzucana przez walidator inList.

Powiązane akcje

  • getCharacteristicsChart — rozkład fraz według cechy jako serie wykresu (ta strona)
  • getCharacteristicsTable — ten sam rozkład w formie tabelarycznej z paginacją i statystykami TOP3/TOP10/TOP50 oraz widocznością
  • W kontrolerze domain_keywords istnieją przestarzałe (deprecated) aliasy tych akcji — używaj ścieżek z kontrolera keywords.
Ostatnia aktualizacja:
SekcjeTabela