リンク分析 API: API キーでクリック統計を取得する

Elido のリンク分析 API は、ワークスペース API キーで認証する https://api.elido.app 上の 1 つのエンドポイント、GET /v1/workspaces/{workspace_id}/analytics/{report} です。クリックの時系列、エンゲージメント概要、上位リンク、カーソルでページングする最近のクリックフィード、国、リファラー、デバイス、ブラウザ、ホスト、リンク先による内訳の 15 個のレポートを提供します。日付のデフォルトは過去 30 日で、link_id を指定すると任意のレポートを 1 つの短縮リンクに絞り込めます。CSV エクスポート、ファネル、コホート、LTV はダッシュボードに残ります。

URL だけ必要だったなら、答えはこれです。このガイドの残りでは、すべてのクリック分析 API ページに最初から書いてあってほしい内容を説明します。正確なパラメータ、返ってくる JSON、想定と静かに異なる日付範囲の動作、そして毎朝 Slack に前日の数値を投稿する 30 行のスクリプトです。

クリックデータを取得する人の多くは、キャンペーンタグ付けから始まる流れを完結させようとしています。まだリンクに一貫した UTM が付いていないなら、まず エンドツーエンドの UTM トラッキング で整えてください。入力がきれいなら、統計を取得する価値も高まります。

リンク分析 API が返す内容

すべてのレポートは同じパスの下にあり、レポート名は最後のセグメントです。スラッシュを含む名前（links/top、clicks/recent、breakdown/country）はエンコードせずに指定します。許可リスト外を要求すると、unknown analytics report という 404 が返ります。

最後の行に注目してください。地域と都市のレポートは、1 つのキーではなく国と地域または都市を各行に持つため、行を items ではなく points に格納します。汎用パーサーがここで失敗するのを一度だけ見たことがあります。一度で十分です。

同じ仕組みが API と SDK、MCP サーバーの分析ツール、n8n ノード の Get Analytics オペレーションを支えています。ここで得た知識はそのまま応用できます。

ワークスペース API キーで認証する

API キーは elido_ で始まり、ちょうど 1 つのワークスペースに属します。キーは Bearer トークンとして送信します。

curl -s "https://api.elido.app/v1/workspaces/4821/analytics/summary" \
  -H "Authorization: Bearer $ELIDO_API_KEY"

ルーターはクエリを実行する前に 2 つを確認します。キーがワークスペース 4821 に属していることと、analytics.view を持っていることです。Viewer を含むすべての組み込みロールにこの権限があります。そのため、レポートジョブには Viewer キーを作成してください。レポート用 cron にリンクを削除する権限は必要ありませんし、Viewer キーでは削除できません。アクセス権のないキーには 403 が返ります。

link_id でアクセス範囲が広がることもありません。パス内のワークスペース ID がチェック対象なので、別のワークスペースから借りたリンク ID は 0 行に一致し、空のリストが返ります。これは正しい失敗です。退屈ですが、何も漏れません。

クリック統計のクエリパラメータ: 日付、タイムゾーン、フィルター

ほぼすべての短縮リンク統計 API 呼び出しは、次の 6 つのパラメータで対応できます。

• from と to は YYYY-MM-DD 形式です。両方省略すると、現在までの過去 30 日が返ります。to だけ設定すると、from はそこから 30 日前になります。
• link_id で任意のレポートを 1 つのリンクに絞り、host で 1 つのリダイレクトドメインに絞ります。ワークスペースで複数のブランドドメインを運用している場合に便利です。
• timeseries の interval は hour または day（デフォルト）です。それ以外はリクエストが失敗します。
• 内訳と上位リストの limit は 1 から 200 で、デフォルトは 50 です。links/top だけは例外で、増やして指定しない限り 10 件を返します。

ここがつまずきやすい詳細です。両方の日付は UTC の午前 0 時として読み取られ、範囲には from が含まれますが to の前で停止します。9 月 21 日全体を取得するには、from=2026-09-21&to=2026-09-22 を送ります。to=2026-09-21 を送ると、その日のデータはまったく返りません。

もう 1 つはタイムゾーンです。IANA タイムゾーン名 として tz を渡すか、X-User-TZ ヘッダーを設定すると、timeseries は現地時間で時間別または日別のバケットを区切ります。動くのはバケットだけです。from/to の範囲は引き続き UTC なので、ベルリンの「昨日」には少し広い範囲が必要です。下のスクリプトがその処理を行います。Europe/Berln のような入力ミスには unknown IANA timezone という 400 が返ります。静かに間違ったグラフになるよりは明確です。

curl -s -G "https://api.elido.app/v1/workspaces/4821/analytics/timeseries" \
  -H "Authorization: Bearer $ELIDO_API_KEY" \
  --data-urlencode "from=2026-09-01" \
  --data-urlencode "to=2026-09-22" \
  --data-urlencode "interval=day" \
  --data-urlencode "tz=Europe/Berlin" \
  --data-urlencode "link_id=918273"

コードで扱えるレスポンス形式

時系列のポイントには、バケット開始時刻を示す RFC 3339 タイムスタンプの ts と count が含まれます。クリック数が 0 のバケットは単純に存在しないため、グラフ化する前に自分で空白を埋めてください。そうしないと、静かな日曜日が X 軸から消えます。

{
  "items": [
    { "ts": "2026-09-19T00:00:00Z", "count": 412 },
    { "ts": "2026-09-21T00:00:00Z", "count": 388 }
  ]
}

内訳はカウント順に並んだ {"items": [{"key": "DE", "count": 1204}, ...]} を返します。概要はフラットなオブジェクトです。

{
  "total_clicks": 5310,
  "unique_visitors": 3987,
  "returning_visitors": 611,
  "avg_clicks_per_visitor": 1.33,
  "bounce_rate": 0.85
}

重要な定義が 2 つあります。ユニーク訪問者は範囲内の異なる IP アドレスで数えるため、1 つの接続の背後にあるオフィスは 1 回として数えられます。また、bounce_rate はパーセンテージではなく割合です。範囲内で 1 回だけクリックしたユニーク訪問者の比率を示します。ランディングページで何が起きたかは示さないため、この数値が GA4 のセッションと一致することはありません。クリックと GA4 セッション の記事でその差を説明しています。すべての数値は届く前にボットが除外されており、Elido のリンク分析 で見るものと同じカウントです。

カーソルで最近のクリックをページングする

clicks/recent は個々のクリックを新しい順で返すリンクトラッキング API レポートです。各行には ts、link_id、slug、host、referer、country_code、device、browser、destination、user_agent、ip があります。ページサイズは 1 から 500 で、デフォルトは 100 です。

ページが満杯で返ると、レスポンスには next_cursor が含まれます。次の、より古いページを取得するには ?cursor= として渡します。null は範囲の末尾に達したことを意味します。

カーソルは最後の行のタイムスタンプとリンク ID を指します。同じリンクへの 2 つのクリックが同じミリ秒で発生すると、ページ境界で同順位になることがあります。最悪の場合は重複行が 1 行発生するだけで、取りこぼしはありません。保存時は完全な行で重複排除してください。まれなケースですが、10 行の挿入処理で済むなら、財務担当者に 1 件のずれを説明するより簡単です。

これらの行には IP アドレスとユーザーエージェントが含まれるため、個人データです。データウェアハウスにコピーする場合は EU 内に保持し、保存期間を設定してください。マーケティングチーム向け EU データレジデンシーガイド で理由を説明しています。ほとんどのレポートでは生の行は不要で、日次集計のほうが誰にとっても負担が少なくなります。

Slack またはスプレッドシート用の日次クリックレポートスクリプト

多くの人が実際に求めているのは、毎朝、前日のクリック数と上位 5 リンクをチャンネルに投稿するジョブです。Python 標準ライブラリと Slack の incoming webhook だけを使います。

import datetime as dt, json, os, urllib.parse, urllib.request
from zoneinfo import ZoneInfo

BASE = "https://api.elido.app/v1/workspaces/{ws}/analytics/{report}"
WS, KEY = os.environ["ELIDO_WORKSPACE_ID"], os.environ["ELIDO_API_KEY"]
TZ = ZoneInfo("Europe/Berlin")

def report(name, **params):
    url = BASE.format(ws=WS, report=name) + "?" + urllib.parse.urlencode(params)
    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {KEY}"})
    with urllib.request.urlopen(req, timeout=20) as r:
        return json.load(r)

day = dt.datetime.now(TZ).date() - dt.timedelta(days=1)
# UTC window one day wider on each side, then keep only local hours of `day`
window = {"from": day - dt.timedelta(days=1), "to": day + dt.timedelta(days=2)}
hours = report("timeseries", interval="hour", tz="Europe/Berlin", **window)["items"]
total = sum(p["count"] for p in hours
            if dt.datetime.fromisoformat(p["ts"]).astimezone(TZ).date() == day)

top = report("links/top", limit=5, **{"from": day, "to": day + dt.timedelta(days=1)})
lines = [f"• {l['slug']}: {l['count']}" for l in top["items"]]
text = f"Clicks on {day} (Berlin): {total}\nTop links (UTC day):\n" + "\n".join(lines)

body = json.dumps({"text": text}).encode()
urllib.request.urlopen(urllib.request.Request(
    os.environ["SLACK_WEBHOOK_URL"], data=body,
    headers={"Content-Type": "application/json"}))

現地時間の 07:00 に cron から実行してください。時間別の処理により、合計が UTC の日ではなくベルリンの 1 日分になります。links/top には tz がないため、ランキングは UTC の日付のままで、メッセージにもそのことが示されます。

スプレッドシートがよければ、同じ 2 つの呼び出しを UrlFetchApp と日次トリガーで Google Apps Script から実行し、1 日 1 行を追加できます。これが Looker Studio ダッシュボード への最も安価な導線でもあります。

まだ毎週月曜日にスクリーンショットから数値を転記しているなら、スクリプトに Viewer キーを渡して、朝の時間を取り戻してください。

ダッシュボード専用で残る機能

API キーの機能は読み取り専用で、意図的にダッシュボードより狭くなっています。キーでは次の機能にアクセスできません。

• CSV クリックエクスポート（clicks.csv）。一括ファイルには、ダッシュボードの「CSV をダウンロード」ボタンを使います。
• ファネル、コホート、LTV レポート、時間別および地理的ヒートマップ、トラフィック品質ビュー。

スケジュールに従ってどこかにファイルが届けば十分なら、ダッシュボードのスケジュール済みメールレポートをコードなしで使えます。サービス移行時のような完全なデータ取得については、短縮リンクアカウントからエクスポートできるもの と、完全性の確認方法を参照してください。また、1 つのリンクについて「すべて」を取得する呼び出しはまだ存在しないため、リンク単位のダッシュボードではレポートごとに 1 回のリクエストが必要です。SDK クイックスタート では、これらを並列実行し、レート制限 に達したときにバックオフする方法を説明しています。

リアルタイムのクリックではクリック分析 API のポーリングか webhook か

率直に言うと、現在クリックデータは取得専用です。Elido の webhook は署名と再試行に対応してリンクイベントとドメインイベントをプッシュしますが、クリックごとの click.created イベントはロードマップ上にあり、まだ発行されていません。クリックについてリアルタイム性が必要なら、clicks/recent をポーリングします。

聞くほど大変ではありません。1〜2 分ごとにポーリングし、すでに保存した行に到達したらすぐ止めれば、負荷はごく小さくなります。静かな 1 分間なら小さなページ 1 つだけだからです。click.created が提供されたときも、行を処理するハンドラーは、それがページから来たのかプッシュされたのかを気にしません。一般的なトレードオフは クリックトラッキングにおける webhook とポーリングの比較 にまとめています。そもそもどの数値をレポートすべきか決めているなら、短縮リンク分析で測定するもの のほうが短く読めます。

私のおすすめは、まず日次概要から始めることです。リアルタイムのクリックを求めるほぼすべてのチームが、コーヒーを飲む前に昨日の数値を受け取れれば満足します。

コーナーストーン記事を読む → UTM キャンペーンをエンドツーエンドで追跡する方法

ブログ内の関連ページ

• URL 短縮サービス API と SDK のクイックスタート - キー、SDK、レート制限、作成呼び出しを解説します。
• n8n URL 短縮ノード - n8n ワークフロー内で同じ分析レポートを使います。
• クリックトラッキングにおける webhook とポーリングの比較 - 連携パターンを選びます。
• Looker Studio のリンク分析 - 日次取得をダッシュボードに変えます。
• MCP で Elido を Claude と Cursor に接続する - 自然な言葉でクリック統計を尋ねます。