メインコンテンツへスキップ
Zenovay
Pro プラン10 minutes中級

API概要

Zenovay APIの紹介 — 機能、認証、プログラムによるアクセスの始め方についてご説明します。このAPI統合ガイドでAPIについて学びましょう。

apideveloperintegrationrest
最終更新日：
Pro プラン

Zenovay APIはアナリティクスデータへのプログラムアクセスを提供します。カスタム統合の構築、ワークフローの自動化、Zenovayの機能拡張が可能です。

できること

外部API（APIキー認証）

機能エンドポイント
アナリティクス概要GET /api/external/v1/analytics/:websiteId
訪問者データGET /api/external/v1/analytics/:websiteId/visitors
ページアナリティクスGET /api/external/v1/analytics/:websiteId/pages
国別データGET /api/external/v1/analytics/:websiteId/countries
テクノロジー内訳GET /api/external/v1/analytics/:websiteId/technology
ウェブサイト一覧GET /api/external/v1/websites
ウェブサイト詳細GET /api/external/v1/websites/:websiteId
API使用状況GET /api/external/v1/usage
ヒートマップページGET /api/external/v1/heatmaps/:websiteId/pages
セッションリプレイGET /api/external/v1/replays/:websiteId/sessions
エラーグループGET /api/external/v1/errors/:websiteId/groups

トラッキング（公開）

これらのエンドポイントはトラッキングスクリプトで使用されます — APIキーは不要です。

機能エンドポイント
ページビュー/イベントの追跡POST /e/:trackingCode
ライブ訪問者数GET /e/live/:trackingCode
ハートビートPOST /e/heartbeat/:trackingCode

プランごとのAPIアクセス

REST APIは有料機能です。無料のワークスペースではAPIキーを作成または使用することはできません — 上記の認証不要なトラッキングエンドポイントはすべてのプランで利用可能です。

プランAPIアクセスリクエスト/分月間制限
Free利用不可——
Proフル3010,000
Scaleフル60100,000
Enterpriseフル1201,000,000

ベースURL

外部APIのベースURLは以下の通りです：

https://api.zenovay.com/api/external/v1

認証

APIキー

X-API-KeyヘッダーまたはAuthorization: BearerヘッダーでAPIキーを使用して認証します：

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

またはBearerトークン認証の場合：

curl https://api.zenovay.com/api/external/v1/websites \
  -H "Authorization: Bearer zv_YOUR_API_KEY"

APIキーは常にzv_プレフィックスで始まります。

APIキーの取得方法

  1. 設定 → セキュリティに移動して、APIキーセクションを開きます
  2. 「APIキーを作成」をクリックします
  3. キーに名前をつけます
  4. スコープを設定します（すべてのウェブサイト、または単一ウェブサイト）
  5. キーをコピーします（一度のみ表示されます）

APIキーはProプラン以上が必要です。無料プランではキー作成ボタンが無効化されています。

詳細は認証をご参照ください。

クイックスタート

ウェブサイト一覧の取得

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

アナリティクスサマリーの取得

アナリティクスエンドポイントはウェブサイトID（UUIDで、上記の「ウェブサイト一覧の取得」のレスポンスからコピー）と、オプションのrange（24h、7d、30d、90d、1yのいずれか）が必要です：

curl "https://api.zenovay.com/api/external/v1/analytics/YOUR_WEBSITE_ID?range=30d" \
  -H "X-API-Key: zv_YOUR_API_KEY"

API使用状況の確認

curl https://api.zenovay.com/api/external/v1/usage \
  -H "X-API-Key: zv_YOUR_API_KEY"

リクエスト形式

ヘッダー

必須ヘッダー（どちらかの形式を使用）：

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

JSONボディを含むPOSTリクエストにはContent-Type: application/jsonを送信してください。

任意ヘッダー：

X-Request-ID: your-unique-id（デバッグ用）

クエリパラメータ

アナリティクスエンドポイントでよく使われるパラメータ：

パラメータ説明例
range時間ウィンドウ：24h、7d、30d、90d、1y（デフォルト7d）?range=30d
limit返す最大行数?limit=50
offsetスキップする行数（ページネーション用）?offset=100

レスポンス形式

成功レスポンス

成功したレスポンスはsuccess/dataエンベロープでラップされています：

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-06-13T00:00:00.000Z"
}

dataオブジェクトの形式はエンドポイントによって異なります（例えば、アナリティクス概要はwebsite、summary、daily_statsを返します）。結果をページネーションするエンドポイントはdata内にpaginationオブジェクトを含みます。

エラーレスポンス

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded (30 requests/minute). Try again in 12 seconds",
    "code": "RATE_LIMIT_EXCEEDED",
    "timestamp": "2026-06-13T00:00:00.000Z"
  }
}

HTTPステータスコード

コード意味
200成功
201作成完了
400リクエストエラー
401認証エラー
403アクセス禁止
404リソースが見つからない
429レート制限超過
500サーバーエラー

クライアントライブラリ

ZenovayにはオフィシャルSDKパッケージはありません。ブラウザ側のトラッキングにはCDNトラッキングスクリプトを使用し、サーバーサイドのAPIアクセスには標準的なHTTPリクエスト（fetch、requests、curl等）をご使用ください。

JavaScript（ブラウザ）

HTMLにトラッキングスクリプトを追加します：

<script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>

グローバルのzenovay関数を使用します：

// イベントをトラック
zenovay('track', 'signup', { plan: 'pro' });

JavaScript（サーバーサイド）

fetchを使用して外部APIを直接呼び出します：

const response = await fetch('https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID', {
  headers: {
    'X-API-Key': 'zv_YOUR_API_KEY',
  },
});
const data = await response.json();

Python（requestsライブラリ使用）

import requests

response = requests.get(
    'https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID',
    headers={'X-API-Key': 'zv_YOUR_API_KEY'}
)
data = response.json()

よくある使用例

カスタムダッシュボード

社内ダッシュボードの構築：

  • 集計指標の取得
  • カスタムビジュアライゼーションの作成
  • 他のデータとの組み合わせ

自動レポート

カスタムレポートの生成：

  • 週次ステークホルダーレポート
  • リアルタイムアラート
  • しきい値モニタリング

CRM統合

CRMとの連携：

  • 訪問者データのプッシュ
  • 連絡先レコードの更新
  • ワークフローのトリガー

レート制限

外部APIのレート制限はAPIキーごと、1分あたりで適用され、キーが属するチームのプランに依存します：

プランリクエスト/分月間制限
Pro3010,000
Scale60100,000
Enterprise1201,000,000

レート制限ヘッダー

すべてのレスポンスには使用状況とレート制限のヘッダーが含まれます：

X-RateLimit-Limit: 30
X-Usage-Monthly: 4521
X-Usage-Limit: 10000
X-Usage-Reset: 2026-07-01T00:00:00.000Z

X-RateLimit-Remainingは利用可能な場合に含まれます。制限を超えると、APIはRetry-Afterヘッダー付きで429を返します。

詳細はレート制限をご参照ください。

ベストプラクティス

効率的なリクエスト

  • 必要なフィールドのみ要求する
  • 日付フィルターを使用する
  • 大きな結果はページネーションで取得する
  • 可能な限りキャッシュを活用する

エラー処理

  • リトライを実装する
  • レート制限を処理する
  • エラーをログに記録する
  • 成功率を監視する

セキュリティ

  • キーを秘密に保つ
  • 最小限の権限を使用する
  • キーを定期的にローテーションする
  • キーの使用状況を監査する

テスト

別のサンドボックスはありません — 専用キーで本番環境に対してテストします：

  1. 設定 → セキュリティに移動して、APIキーセクションを開きます
  2. キーを作成して、認識可能な名前をつけます（例：「Test」）
  3. 可能であれば単一のテストウェブサイトにスコープします
  4. 標準API URLを使用します：https://api.zenovay.com/api/external/v1/
  5. 完了後はキーを削除します

サポート

ヘルプの取得

変更履歴

製品およびAPIの変更を追跡：docs.zenovay.com/changelog

次のステップ

関連記事

  1. REST APIリファレンス

    REST APIの完全なリファレンス — Zenovay APIのすべてのエンドポイント、パラメータ、レスポンス形式。このAPI統合ガイドでAPIについて詳しく学びます。

  2. アナリティクスをプログラムで照会するにはどうすればよいですか（Stats API）？

    HTTP 経由で Zenovay のアナリティクスデータを照会します — 合計値、時系列、 ページ・国・ブラウザなどのディメンション別内訳。Plausible 互換の パラメーター構造で簡単に移行できます。

  3. Webhook

    プラットフォームイベントが発生した際にZenovayからリアルタイム通知を受け取るためのアウトバウンドWebhookの設定方法と、Zenovayが内部でインバウンド決済Webhookを処理する仕組みについて説明します。

この記事は役に立ちましたか？