Stats API は、HTTP 経由で Zenovay のアナリティクスを取得できる、公開されたレート制限付きのクエリインターフェイスです。カスタムダッシュボードの構築、BI ツールへのライブメトリクスの埋め込み、または Plausible からのスクリプト移行に使用できます。
照会できる内容
| エンドポイント | 返されるデータ |
|---|---|
GET /stats/aggregate | 期間内の合計値（訪問者数、ページビュー数、直帰率、平均セッション時間）。 |
GET /stats/timeseries | 期間内の日次・時間次・月次の 1 データポイント。 |
GET /stats/breakdown | 上位ページ、上位国、上位ブラウザ — 訪問者数で並べた任意の単一ディメンション。 |
完全なリファレンス、パラメーター表、使用例：docs.zenovay.com/api/external-api（「Stats API」セクションを参照）。
ライブの OpenAPI 3.1 仕様は /api/external/v1/openapi.json で参照できます。Postman や Insomnia にインポートするか、コード生成ツールと組み合わせてご使用ください。
プラン要件
Stats API は Pro、Scale、Enterprise プランでご利用いただけます。Free プランは API キーの作成や使用ができず、エンドポイントへのコールは 403 API_PAID_PLAN_REQUIRED エラーを返します。設定 → 請求 からアップグレードしてください。
プランごとのレート制限
| プラン | レート制限（1 分あたり、目標値） | 月次リクエスト上限 |
|---|---|---|
| Free | 10 | 1,000 |
| Pro | 30 | 10,000 |
| Scale | 60 | 100,000 |
| Enterprise | 120 | 1,000,000 |
プランのレート制限を超えると、API は 429 Too Many Requests を返します。レスポンスには Retry-After ヘッダーが含まれ、何秒待てばよいかが示されます。
レート制限の仕組み。 1 分あたりの制限は目標値であり、厳密な上限ではありません。Cloudflare のエッジレート制限を使用しており、データセンターごとに少量のバースト許容量があります。そのため、継続的なクライアントはリクエストが複数のリージョンに分散する場合、スロットリングされる前に一時的に記載値の 1.5～3 倍を見ることがあります。ハードキャップは月次リクエスト上限であり、リクエストの発生場所に関わらずアカウントに対してアトミックに適用されます。容量に敏感なワークロードは月次上限を基準に計画し、1 分あたりの数値はスムージングの目標として扱ってください。
クイックスタート
- API キーを取得する（Pro 以上）— API キーはどこで取得できますか？ を参照。キーは
zv_で始まります。 - サイトの UUID を確認する — Zenovay ダッシュボードでウェブサイトを開きます。UUID は URL に含まれています：
app.zenovay.com/domains/<UUID>。 - 最初の呼び出しを実行する：
curl -G "https://api.zenovay.com/api/external/v1/stats/aggregate" \
-H "X-API-Key: zv_YOUR_KEY" \
--data-urlencode "site_id=YOUR_SITE_UUID" \
--data-urlencode "period=7d" \
--data-urlencode "metrics=visitors,pageviews"
次のようなレスポンスが返されます：
{
"success": true,
"data": {
"results": {
"visitors": { "value": 12453 },
"pageviews": { "value": 38219 }
},
"meta": { "period": "7d", "period_start": "...", "period_end": "..." }
}
}
よくあるユースケース
- カスタムダッシュボード — 集計メトリクスを毎時間 Notion、Coda、Retool、または社内の BI ツールに取り込みます。
- Plausible からの移行 — パラメーターの構造（
site_id、period、date、metrics、filters、property）は意図的に Plausible と互換性を持たせています。ほとんどの移行スクリプトは、ベース URL を置き換えてsite_idをドメインから Zenovay の UUID に再マッピングするだけで動作します。 - 埋め込み — ステータスページやマーケティングサイトにライブ訪問者数を表示します（サーバーサイドプロキシを使用してください。API キーをクライアントサイドのコードに公開しないでください）。
- 定期レポート — ブレークダウンデータを 1 日 1 回取得して Slack またはメールに投稿します。
フィルター
Plausible 形式のフィルターを使用して、クエリを訪問者のサブセットに絞り込めます：
# 米国の訪問者のみ
--data-urlencode "filters=country==US"
# 米国とカナダの訪問者（Chrome を使用）
--data-urlencode "filters=country==US,CA;browser==Chrome"
# /admin ページ以外のすべての訪問者
--data-urlencode "filters=page!=/admin"
使用可能なフィルターキー： country、browser、device、os、source、utm_source、utm_medium、utm_campaign、page。
V1 の制限：
filtersを指定した場合、V1 ではvisitorsメトリクスのみが計算されます。その他のメトリクスはnullを返し、meta.noteフラグが付きます。すべてのメトリクスへの完全なフィルターサポートは V2 でリリースされます。フィルターなしのクエリは今日からすべてのメトリクスをサポートしています。
トラブルシューティング
| 症状 | 原因 | 対処法 |
|---|---|---|
401 UNAUTHORIZED "Missing API key" | X-API-Key または Authorization: Bearer ヘッダーがない | ヘッダーを追加してください。キーがない場合は 設定 → アカウント → セキュリティとアクセス で生成してください。 |
401 UNAUTHORIZED "Invalid API key" | キーが失効しているか、タイプミスがあるか、zv_ で始まっていない | 設定 → アカウント → セキュリティとアクセス から再コピーしてください。 |
403 FORBIDDEN "requires a Pro plan" | チームが Free プランを使用している | 設定 → 請求 からアップグレードしてください。 |
403 FORBIDDEN "does not have access" | API キーが特定のサイトにスコープされているが、site_id が一致しない | フルアクセスキーを作成するか、正しい site_id で呼び出してください。 |
404 NOT_FOUND "Website not found" | site_id UUID が誤っている | ダッシュボードの URL で確認してください。 |
400 MISSING_* | 必須クエリパラメーターがない | site_id、period、metrics を追加してください（常に必須）。 |
400 INVALID_METRIC | 不明なメトリクス名 | visitors、pageviews、visit_duration、bounce_rate、または events を使用してください。 |
400 INTERVAL_PERIOD_MISMATCH | interval=hour に day 以外の period を使用している | period=day と interval=hour を組み合わせるか、長い期間には interval=day を使用してください。 |
429 Too Many Requests | プランのレート制限に達した | Retry-After ヘッダーを確認してください。頻繁に達する場合はプランのアップグレードをご検討ください。 |
Plausible からの移行
パラメーターの構造は意図的に Plausible の Stats API v1 に近づけています。相違点：
| Plausible | Zenovay | 注記 |
|---|---|---|
site_id=mysite.com | site_id=<UUID> | Plausible はドメイン文字列を使用。Zenovay は UUID を使用。GET /websites で 1 回マッピングしてください。 |
period、date | period、date | 同じ許可リスト + custom:YYYY-MM-DD,YYYY-MM-DD。 |
metrics | metrics | visitors、pageviews、bounce_rate、visit_duration は 1 対 1 でマッピングされます。 |
filters（v1 文字列形式） | filters | 同じ key==value;key!=value 形式。 |
filters（v2 JSON 配列） | （Zenovay Stats API の V2） | 後日リリース予定。 |
次のステップ
- Stats API 完全リファレンス（ドキュメント） — すべてのパラメーター、エンドポイント、エラーコード。
- OpenAPI 3.1 仕様 — コード生成と API テストツール用。
- 認証 — Bearer と X-API-Key ヘッダー、キーのローテーション。
- API の概要 — その他の Zenovay 公開エンドポイント（インサイト、異常検知、リテンション、LTV、自然言語クエリ）。