Uzyskaj analizę centrum pomocy za pomocą interfejsu API Notiondesk

Interfejs API Notiondesk udostępnia dane liczbowe dotyczące stron analitycznych w centrum pomocy: liczbę odwiedzających, liczbę wyświetleń artykułów, czas spędzony na stronie, kraje, wyszukiwane hasła, wyszukiwania, które nie przynoszą rezultatów, oraz reakcje czytelników na artykuły. Można go używać do zasilania narzędzia BI, publikowania cotygodniowych raportów w Slacku lub wyszukiwania treści, których brakuje czytelnikom.

GET /sites/{site_id}/analytics/{report}

Każdy raport wymaga zakresu read. Aby odczytać te liczby w panelu, zapoznaj się z artykułem „Jak ulepszyć centrum pomocy dzięki analizom czytelników” .

Uzyskaj podsumowanie 30-dniowe

quick obejmuje ostatnie 30 dni, kończące się teraz, i nie przyjmuje żadnych parametrów zapytania. articles zlicza wszystkie artykuły w centrum pomocy, w tym wersje robocze. reactions zlicza najnowszą reakcję każdego czytelnika na artykuł.

Pobierz raport dla zakresu dat

overview, search i engagement przyjmują zakres dat i rozmiar kontenera:

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/analytics/quick" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "articles": 42,
  "visitors": 25,
  "searches": 9,
  "reactions": 4
}

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/analytics/search?start_date=2026-09-01T00:00:00Z&end_date=2026-10-01T00:00:00Z&date_scale=week&timezone=Europe/Paris" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

Zasady dotyczące zakresu:

• Daty używają YYYY-MM-DDTHH:MM[:SS] z opcjonalnym przesunięciem. Bez przesunięcia data jest odczytywana w formacie UTC, a nie timezone. Wpisz + jako %2B w adresie URL lub użyj Z.

• Zakres zaczyna się 2020-01-01 lub później i kończy się najpóźniej za dwa dni od teraz.

• Maksymalnie 1000 wiader. Na przykład minute pokrywa maksymalnie 16 godzin, a hour maksymalnie 41 dni. Użyj grubszego date_scale do większych zasięgów.

• Tydzień zaczyna się w poniedziałek.

Każdy raport porównuje zakres z okresem o tej samej długości tuż go poprzedzającym: previous i total_previous opisują ten wcześniejszy okres.

Seria liczbowa

visitors, article_views i searches mają jeden wspólny kształt:

{
  "total": 12,
  "total_previous": 8,
  "difference": 4,
  "percentage_difference": 50.0,
  "current": [{"date": "2026-09-14", "count": 7}, {"date": "2026-09-15", "count": 5}],
  "previous": [{"date": "2026-08-20", "count": 8}]
}

• current i previous wyświetlają tylko te kontenery, które zawierają dane, najpierw najstarsze.

• date wiadra to stan początkowy, w timezone: YYYY-MM-DD dla day i grubszych, YYYY-MM-DDTHH:MM dla hour i minute.

• percentage_difference wynosi 0.0, gdy poprzednia suma wynosiła 0.

overview

search

{
  "searches_without_results": {
    "total": 3,
    "total_previous": 0,
    "difference": 3,
    "percentage_difference": 0.0,
    "queries": [{"query": "refund policy", "searches": 3}]
  }
}

Uwaga: jeśli chodzi o zaległości w treściach: każde zapytanie jest pytaniem zadawanym przez czytelników, na które Twoje centrum pomocy nie było w stanie odpowiedzieć. searches_without_results.queries

engagement

reaction_summary podąża za Twoim stylem reakcji:

score to skala od 0 do 100: odsetek reakcji pozytywnych, przy czym reakcja neutralna jest o połowę mniejsza od emoji. W stylu thumbs grupy to helpful i not_helpful. Zobacz Jak zbierać opinie za pomocą reakcji na artykuły .

Limity listy

{
  "style": "emoji",
  "total": 6,
  "score": 58,
  "groups": [
    {"key": "positive", "count": 3, "percent": 50},
    {"key": "neutral", "count": 1, "percent": 17},
    {"key": "negative", "count": 2, "percent": 33}
  ]
}

• Listy zapytań top_articles, top_referrers, article_engagements i articles_to_revise zawierają do 50 wierszy każda i obejmują tylko bieżący okres. Lista 50 wierszy może być niekompletna: zawęź zakres, aby wyświetlić wszystkie wiersze.

• Podane sumy obejmują wszystko, nie tylko wymienione wiersze.

title, , , , i pochodzą z przeglądarek użytkowników i każdy może je sfałszować. Unikaj ich wyświetlania i nigdy nie śledź ich ani nie wykonuj żadnych działań bez sprawdzenia.urlhostpathnamereferrerquery

Analityka i Twój plan

Dostęp do interfejsu API wymaga planu Enterprise, który obejmuje zaawansowaną analitykę, dzięki czemu każdy raport akceptuje dowolny zakres i skalę w ramach 1000 przedziałów.

Limit szybkości

Oprócz 120 odczytów klucza na minutę, raporty analityczne wliczają się do budżetu 30 żądań na minutę na centrum pomocy , współdzielonego przez każdy klucz i aplikację OAuth w Twojej przestrzeni roboczej. Żądanie nad nim odpowiada na 429 rate_limited, a jego nagłówek Retry-After wskazuje, kiedy ponowić próbę. Buforuj raporty zamiast żądać ich przy każdym załadowaniu strony.

Błędy

Zobacz Obsługa błędów interfejsu API Notiondesk, limitów szybkości i ponownych prób .

Często zadawane pytania

Co dalej?

• Eksportuj opinie czytelników za pomocą interfejsu API Notiondesk

• Zautomatyzuj typowe zadania centrum pomocy za pomocą interfejsu API Notiondesk

• Obsługa błędów API Notiondesk, limitów szybkości i ponownych prób