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

REST APIリファレンス

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

apirestreferenceendpointsdeveloper
最終更新日：
Pro プラン

Zenovay REST APIのすべてのエンドポイントの完全なリファレンスです。使い始めるには、API概要をご参照ください。

クライアントを生成する場合は、https://api.zenovay.com/api/external/v1/openapi.jsonで公開されているマシン可読のOpenAPI仕様が利用可能です。

外部API

外部APIはAPIキー認証を使用し、有料機能です — Pro、Scale、Enterpriseプランで利用可能です。無料層のキーは403 API_PAID_PLAN_REQUIREDで拒否されます。

ベースURL

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

認証

アカウント → セキュリティとアクセスでキーを生成します（またはapp.zenovay.com/api-keysを直接開きます）。キーはzv_で始まります。次のヘッダーを使用して、すべてのリクエストにキーを含めます：

X-API-Key: zv_YOUR_API_KEY
# または
Authorization: Bearer zv_YOUR_API_KEY

レスポンスエンベロープ

外部APIのすべてのレスポンスは標準エンベロープでラップされています。成功したレスポンスは次のようになります：

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

以下の例はdataオブジェクトの内容を示します。エラーは異なる形式を使用します — エラーレスポンスを参照してください。

アナリティクスエンドポイント

アナリティクス概要の取得

GET /analytics/{websiteId}

ウェブサイトのアナリティクスデータの集計サマリーを返します。

クエリパラメータ：

パラメータ型説明
rangestring時間範囲：24h、7d、30d、90d、1y（デフォルト：7d）

data:

{
  "website": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "example.com",
    "name": "My Website"
  },
  "time_range": "7d",
  "date_range": {
    "start": "2026-06-06",
    "end": "2026-06-13"
  },
  "summary": {
    "total_visitors": 1247,
    "total_page_views": 3891,
    "unique_visitors": 982
  },
  "daily_stats": []
}

daily_statsは指定された範囲の生のanalytics_daily行を含みます。Plausible形式のクエリAPI（フィルターとブレークダウン付きvisitors、pageviews、bounce_rate、visit_duration）については、Stats APIを参照してください。

訪問者の取得

GET /analytics/{websiteId}/visitors

ウェブサイトの個別訪問者レコードを返します。

クエリパラメータ：

パラメータ型説明
rangestring時間範囲（デフォルト：7d）
limitintegerページあたりの結果数（デフォルト：100、最大：1000）
offsetintegerスキップするレコード数（デフォルト：0）

ページの取得

GET /analytics/{websiteId}/pages

ウェブサイトのトップページを返します。rangeとlimitを受け付けます（デフォルト20、最大100）。

国の取得

GET /analytics/{websiteId}/countries

国別の訪問者の地理的ブレークダウンを返します。rangeとlimitを受け付けます（デフォルト20、最大100）。

テクノロジーの取得

GET /analytics/{websiteId}/technology

テクノロジーブレークダウン — devices、browsers、operating_systemsを返します。各項目にはカウントとパーセンテージが含まれます。rangeを受け付けます。

ウェブサイトエンドポイント

ウェブサイト一覧の取得

GET /websites

APIキーでアクセス可能なすべてのウェブサイトを返します。

data:

{
  "websites": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "domain": "example.com",
      "name": "My Website",
      "tracking_code": "abc123def456",
      "is_active": true,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

ウェブサイト詳細の取得

GET /websites/{websiteId}

data.websiteの下の特定のウェブサイトの詳細を返します。

ヒートマップエンドポイント

ヒートマップページの取得

GET /heatmaps/{websiteId}/pages

ヒートマップデータが収集されたページを返します。limitを受け付けます（デフォルト20、最大100）。

セッションリプレイエンドポイント

リプレイセッションの取得

GET /replays/{websiteId}/sessions

ウェブサイトのセッションリプレイ録画を返します。limit（デフォルト50、最大200）とoffsetを受け付けます。

エラートラッキングエンドポイント

エラーグループの取得

GET /errors/{websiteId}/groups

ウェブサイトのグループ化されたエラーデータを返します。limit（デフォルト50、最大200）と、オプションのstatusフィルター（open、resolved、ignored）を受け付けます。

AI＆高度なエンドポイント（Pro+）

これらのエンドポイントはProプラン以上が必要であり、所有者ウェブサイトのチームプランに基づいて制限されます。

エンドポイント説明
GET /insights/{websiteId}サイト用のAIが生成したインサイト
GET /anomalies/{websiteId}検出されたトラフィック/行動異常
GET /retention/{websiteId}リテンションコホート分析（granularity、periods）
GET /revenue/{websiteId}/ltvライフタイムバリューコホート分析

自然言語クエリ（Scale+）

POST /query/{websiteId}

自然言語アナリティクスクエリを実行します。Scale以上のプランが必要です。query文字列（最大500文字）を含むJSONボディを送信してください。各呼び出しは3クエリクレジットを消費します。

Stats API

Plausible互換の読み取り専用クエリエンドポイント（Pro+）。これらにより、フィルター付きのメトリクス、時系列、ブレークダウンをクエリできます。完全なパラメータリファレンスについては、専用のStats APIガイドを参照してください。

エンドポイント説明
GET /stats/aggregate期間内の単一数値メトリクス
GET /stats/timeseries時間離散化されたシリーズ（interval=day/hour/month）
GET /stats/breakdownグループ化メトリクス（トップページ、トップ国など）

3つすべてがsite_idとperiod、metrics、およびオプションのfiltersを必要とします。サポートされるメトリクスはvisitors、pageviews、bounce_rate、visit_duration、eventsです。

使用状況エンドポイント

API使用状況の確認

GET /usage

現在のAPI使用状況と制限を返します。

data:

{
  "api_key": {
    "id": "key_123",
    "name": "Personal API key",
    "permission": "full_access",
    "website_id": null,
    "auth_kind": "user"
  },
  "usage": {
    "monthly_requests": 4521,
    "monthly_limit": 10000,
    "monthly_remaining": 5479,
    "monthly_reset_at": "2026-07-01T00:00:00.000Z",
    "total_requests": 18204,
    "scope": "user"
  },
  "rate_limits": {
    "requests_per_minute": 30
  },
  "subscription": {
    "tier": "Pro"
  }
}

トラッキングエンドポイント（公開）

これらのエンドポイントはAPIキー認証を必要としません。ウェブサイトのトラッキングコードを使用し、すべてのプランで開放されています（レート制限のみ）。

ページビュー/イベントのトラック

POST /e/{trackingCode}

ページビューまたはカスタムイベントを送信します。これはトラッキングスクリプトが自動的に呼び出すものです。サーバーサイドトラッキングの場合は、適切なヘッダーとともに同じペイロード形式を送信してください。ハートビートイベントもこのエンドポイントにheartbeatイベントタイプとして送信できます。

ライブ訪問者数

GET /e/live/{trackingCode}

サイト上の現在のライブ訪問者数を、アクティブなセッションの簡潔なリストとともに返します。

ハートビート

POST /e/heartbeat/{trackingCode}

訪問者セッションを保持するためのハートビートを送信します。JSONボディでsession_idが必要です。

エラーレスポンス

エラー形式

エラーはsuccess: falseとerrorオブジェクトとともに返されます：

{
  "success": false,
  "error": {
    "message": "site_id parameter is required",
    "code": "MISSING_SITE_ID",
    "timestamp": "2026-06-13T00:00:00.000Z"
  }
}

よくあるエラーコード

コードHTTPステータス説明
UNAUTHORIZED401APIキーが無効または不足
API_PAID_PLAN_REQUIRED403APIアクセスにはProプラン以上が必要
FORBIDDEN403キーがリクエストされたサイトへのアクセス権がない、またはプランティアが低い
NOT_FOUND404リソースが見つかりません
VALIDATION_ERROR400不正なパラメータまたは不足しているパラメータ
MISSING_SITE_ID400site_idクエリパラメータが必要です（Stats API）
RATE_LIMIT_EXCEEDED4291分あたりのレート制限を超過
MONTHLY_LIMIT_EXCEEDED429月間APIリクエスト制限に達した
INTERNAL_ERROR500内部エラー

レート制限

外部APIのレート制限はAPIキーごとに適用されます。（無料行は完全性のため表示されていますが、無料層のキーは外部APIを呼び出せません — これは有料機能です。）

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

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

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

1分ごとの制限に達した場合、レスポンスにはRetry-Afterヘッダー（待機秒数）も含まれます。

次のステップ

関連記事

  1. API概要

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

  2. APIはどう動作しますか？APIキーはどうやって取得しますか？

    ZenovayのREST APIはzv_で始まるBearerトークンを使用します。生成、スコープ設定、 取り消しの方法、加えて30秒のhello-worldリクエストをご説明します。

  3. リアルタイムデータアクセス

    Zenovay上にライブダッシュボードを構築する — ポーリング戦略、外部API、およびリアルタイムデータの出所。

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