Notiondesk API を使用してヘルプセンターの分析情報を取得します。

Notiondesk API を使用すると、ヘルプセンターの分析ページに関するデータ（訪問者数、記事閲覧数、ページ滞在時間、国別データ、読者の検索キーワード、検索結果がなかった検索キーワード、記事に対する読者の反応など）を取得できます。この API を活用して BI ツールにデータを供給したり、Slack に週次レポートを投稿したり、読者が求めているコンテンツを見つけたりすることができます。

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

`report`	含まれる
`quick`	30日間のサマリー：記事数、訪問者数、検索数、反応
`overview`	訪問者数、記事閲覧数、ページ滞在時間、上位国
`search`	検索、上位クエリ、検索結果なしの検索、クリック率
`engagement`	記事閲覧数、人気記事、参照元、反応、修正対象記事

すべてのレポートには、read スコープが必要です。ダッシュボードでこれらの数値を確認するには、「読者のインサイトを活用してヘルプセンターを改善する方法」を参照してください。

30日間のサマリーを取得する

quick は現在までの過去 30 日間を対象とし、クエリパラメータは不要です。articles は、ヘルプセンターのすべての記事（下書きを含む）をカウントします。reactions は、記事ごとに各読者の最新の反応をカウントします。

指定した日付範囲のレポートを取得する

overview、search、およびengagementは、日付範囲とバケットサイズを受け取ります。

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
}

パラメータ	必須	注記
`start_date`	はい	範囲の最初の瞬間、例えば `2026-09-01T00:00:00Z`
`end_date`	はい	範囲の末尾は除外されます。`start_date` の後である必要があります。
`date_scale`	はい	時系列データのバケットサイズ：`minute`、`hour`、`day`、`week`、`month`、または`year`
`timezone`	いいえ	バケット境界を設定するIANAタイムゾーン。例: `Europe/Paris`。デフォルトは`UTC`。

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"

射撃場のルール：

日付は、オプションのオフセット付きで YYYY-MM-DDTHH:MM[:SS] を使用します。オフセットがない場合、日付は timezone ではなく UTC として読み取られます。URL では + を %2B と記述するか、Z を使用してください。

期間は2020年1月1日以降に開始し、最大で今日から2日後に終了します。

最大1,000個のバケットまで。例えば、minuteは最大16時間、hourは最大41日間をカバーします。より長い範囲をカバーするには、より粗いdate_scaleを使用してください。

週は月曜日から始まります。

各レポートは、あなたの範囲をその直前の同じ長さの期間と比較します。previous と total_previous は、その直前の期間を表します。

カウントシリーズ

visitors、article_views、およびsearchesは、同じ形状を共有しています。

{
  "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 と previous には、データのあるバケットのみが、古いものから順にリストされます。

バケットの date は、timezone の開始位置です。YYYY-MM-DD は day より粗いバケットの場合、YYYY-MM-DDTHH:MM は hour および minute の場合です。

前回の合計が 0 の場合、percentage_difference は 0.0 になります。

`overview`

分野	意味
`visitors`	カウントシリーズ。`total` は、範囲内の異なる訪問者数であり、ポイントの合計ではありません。
`article_views`	記事ページの閲覧回数をカウントする
`session_durations`	読者がページに費やす時間（秒）：`average_seconds`、および`current`と`previous`のリスト`{date, seconds}`
`top_countries`	最大10か国：`country`（ISOコード）、`country_name`、`visitors`

`search`

分野	意味
`searches`	検索回数をカウント
`searches_with_results`	合計と`queries`リスト：`query`、`searches`、`clicks`、`articles_shown`、`click_through_rate`、`avg_click_position`
`searches_without_results`	合計と`queries`リスト：`query`と`searches`
`click_through_rate`	クリックにつながった検索結果の割合（パーセント）：`current`、`previous`、`difference`、`percentage_difference`

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

注:はコンテンツのバックログです。各クエリは、読者から寄せられた質問で、ヘルプセンターで回答できなかったものです。 searches_without_results.queries

`engagement`

分野	意味
`overview.current`、`overview.previous`	各期間ごとに `views`、`articles_to_revise`、および `reaction_summary` があります。
`article_views`	記事ページの閲覧回数をカウントする
`top_articles`	最も閲覧された記事：`title`、`host`、`pathname`、`views`
`top_referrers`	訪問者の出身地：`referrer`（直接訪問の場合は`null`）および`visitors`
`article_engagements`	読者から最も好意的な反応を得た記事は、`title`、`url`、`views`、`reaction_summary`です。
`articles_to_revise`	読者が最も否定的な反応を示した記事は、同じ分野で

reaction_summaryはあなたの反応スタイルに従います：

score は 0 から 100 までの値を取り、肯定的な反応の割合を示します。中立的な反応は emoji で半分としてカウントされます。thumbs スタイルでは、グループは helpful と not_helpful です。記事の反応でフィードバックを収集する方法を参照してください。

リスト制限

{
  "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}
  ]
}

クエリリストtop_articles、top_referrers、article_engagements、およびarticles_to_reviseには、それぞれ最大50行が格納され、現在の期間のみを対象としています。50行のリストは不完全な場合があります。すべての行を表示するには、範囲を絞り込んでください。

合計値は、リストに記載されている行だけでなく、すべての項目を対象としています。

title、、、、は訪問者のブラウザから取得されるものであり、誰でも偽造できます。表示する前にエスケープ処理を行い、検証せずに追跡したり、それに基づいて行動したりしないでください。urlhostpathnamereferrerquery

分析とプラン

APIへのアクセスにはエンタープライズプランが必要で、これには高度な分析機能が含まれているため、すべてのレポートで1,000バケット以内の任意の範囲とスケールを指定できます。

レート制限

キーの1分あたり120回の読み取りに加え、分析レポートは、ワークスペース内のすべてのキーとOAuthアプリで共有される、ヘルプセンターごとに1分あたり30回のリクエストという予算にカウントされます。このレポートに対するリクエストは429 rate_limitedという応答を返し、Retry-Afterヘッダーは再試行のタイミングを示します。ページ読み込みごとにレポートをリクエストするのではなく、キャッシュしてください。

エラー

状態	いつ	`code`
400	パラメータが欠落しているか、形式が不正であるか、不明であるか、`quick` がパラメータを受け取ったか、範囲ルールが失敗したかのいずれかです。`errors` リストには、パラメータとルールの名前が記載されています。	`validation_error`
403	キーには`read`スコープがありません	`insufficient_scope`
403	ヘルプセンターでは分析機能が無効になっています	`permission_denied`
404	`report` は 4 つのレポートのいずれにも該当しないか、またはワークスペースにヘルプセンターが存在しません。	`not_found`
429	ヘルプセンターの分析予算が使い果たされました	`rate_limited`
503	分析サービスから応答がありませんでした。再試行するか、範囲を絞り込んでください。	`internal_error`

API エラー、レート制限、および再試行の処理については、「Notiondesk API エラーの処理」を参照してください。

よくある質問

読者が検索しているのに見つけられない情報を見つけるにはどうすればいいですか？

search レポートを呼び出し、searches_without_results.queries を読み込んでください。各エントリは、記事が返されなかったクエリと、そのクエリが検索された回数を示しています。

なぜ私のレポートは`dateScale`に関して400エラーを返すのですか？

date_scale の範囲には 1,000 個以上のバケットが含まれています。hour の代わりに day のようなより粗いスケールを使用するか、範囲を短くしてください。メッセージには dateScale と表示されていますが、パラメーターは date_scale です。

リストが50行で打ち切られるのはなぜですか？

リストには最大50行まで格納できます。長い範囲を短い範囲に分割すると、より多くのクエリや記事を表示できます。

記事1つ分の分析データを取得することはできますか？

レポートはヘルプセンター全体を対象としています。各記事の閲覧数と反応数も、views_count および reactions_percent として記事リストに表示されます。

次は？

Notiondesk API を使用して読者のフィードバックをエクスポートします

Notiondesk API を使用して、ヘルプセンターの一般的なタスクを自動化します。

Notiondesk APIエラー、レート制限、および再試行を処理する

目次