メインコンテンツへスキップ
Zenovaydocs
10分で読めます

外部 API

外部 API により、Zenovay アナリティクスデータを顧客向けウェブサイトに埋め込むことができます。API キーを使用して、ライブアクセス数、アナリティクスサマリー、ページ統計など、様々なデータをフェッチできます。

ベース URL

すべての外部 API リクエストは以下のアドレスに送信してください:

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

認証

外部 API エンドポイントはリクエストヘッダーで渡された API キーが必須です:

API Key HeaderBash
curl -X GET 'https://api.zenovay.com/api/external/v1/websites' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json'

API キーは 設定 → セキュリティ → API キー から生成してください。各キーには特定のパーミッション (読み取り、書き込み、管理者) を設定できます。

外部 API は有料プランが必須です。 フリーティアのアカウントはすべてのエンドポイントで 403 API_PAID_PLAN_REQUIRED レスポンスを受け取ります。Pro、Scale、または Enterprise にアップグレードして API キーをプログラムで使用してください。

アカウントエンドポイント

アカウント使用状況の取得

アカウントの使用状況統計と制限を取得します:

GET/api/external/v1/usage

アカウント使用状況と制限を取得

リクエストBash
curl -X GET 'https://api.zenovay.com/api/external/v1/usage' \
-H 'X-API-Key: YOUR_API_KEY'
レスポンス (200 OK)JSON
{
"usage": {
  "websites": 5,
  "pageviews_this_month": 125000,
  "events_this_month": 45000
},
"limits": {
  "websites": 10,
  "pageviews_per_month": 500000,
  "events_per_month": 100000
},
"plan": "pro",
"period": {
  "start": "2025-01-01T00:00:00Z",
  "end": "2025-01-31T23:59:59Z"
}
}

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

ウェブサイト一覧の取得

アカウントにリンクされているすべてのウェブサイトを取得します:

GET/api/external/v1/websites

追跡されているすべてのウェブサイトを一覧表示

リクエストBash
curl -X GET 'https://api.zenovay.com/api/external/v1/websites' \
-H 'X-API-Key: YOUR_API_KEY'
レスポンス (200 OK)JSON
{
"websites": [
  {
    "id": "ws_abc123",
    "domain": "example.com",
    "name": "Example Website",
    "tracking_code": "ZV_XXXXXXXXXXX",
    "created_at": "2025-01-01T00:00:00Z",
    "live_visitors": 42
  },
  {
    "id": "ws_def456",
    "domain": "shop.example.com",
    "name": "Example Shop",
    "tracking_code": "ZV_YYYYYYYYYYY",
    "created_at": "2025-01-10T00:00:00Z",
    "live_visitors": 18
  }
],
"total": 2
}

ウェブサイト詳細の取得

特定のウェブサイトの詳細を取得します:

GET/api/external/v1/websites/:websiteId

ウェブサイト詳細を取得

リクエストBash
curl -X GET 'https://api.zenovay.com/api/external/v1/websites/ws_abc123' \
-H 'X-API-Key: YOUR_API_KEY'
レスポンス (200 OK)JSON
{
"website": {
  "id": "ws_abc123",
  "domain": "example.com",
  "name": "Example Website",
  "tracking_code": "ZV_XXXXXXXXXXX",
  "created_at": "2025-01-01T00:00:00Z",
  "settings": {
    "track_outbound_links": true,
    "track_downloads": true,
    "session_replay": true
  }
},
"stats": {
  "live_visitors": 42,
  "today_pageviews": 1234,
  "today_visitors": 567
}
}

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

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

ウェブサイトの包括的なアナリティクスデータを取得します:

GET/api/external/v1/analytics/:websiteId

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

クエリパラメータ:

パラメータ型必須説明
timeRangestringいいえ期間: today、7d、30d、90d (デフォルト: 7d)
リクエストBash
curl -X GET 'https://api.zenovay.com/api/external/v1/analytics/ws_abc123?timeRange=30d' \
-H 'X-API-Key: YOUR_API_KEY'
レスポンス (200 OK)JSON
{
"summary": {
  "visitors": 12543,
  "pageviews": 45231,
  "sessions": 15420,
  "bounce_rate": 0.42,
  "avg_session_duration": 185,
  "pages_per_session": 2.9
},
"period": {
  "start": "2024-12-21T00:00:00Z",
  "end": "2025-01-20T23:59:59Z"
},
"live_visitors": 42
}

ビジターデータの取得

オプションのフィルタリング機能を備えたビジター情報を取得します:

GET/api/external/v1/analytics/:websiteId/visitors

ビジターデータを取得

クエリパラメータ:

パラメータ型必須説明
timeRangestringいいえ期間: today、7d、30d、90d
limitintegerいいえ最大結果数 (デフォルト: 50、最大: 100)
offsetintegerいいえページネーションオフセット
リクエストBash
curl -X GET 'https://api.zenovay.com/api/external/v1/analytics/ws_abc123/visitors?timeRange=7d&limit=10' \
-H 'X-API-Key: YOUR_API_KEY'
レスポンス (200 OK)JSON
{
"visitors": [
  {
    "visitor_id": "vis_abc123",
    "first_seen": "2025-01-15T10:00:00Z",
    "last_seen": "2025-01-20T14:30:00Z",
    "total_sessions": 8,
    "total_pageviews": 45,
    "value_score": 87,
    "country": "US",
    "device": "desktop"
  }
],
"total": 1234,
"limit": 10,
"offset": 0
}

ページアナリティクスの取得

ページレベルの統計情報を取得します:

GET/api/external/v1/analytics/:websiteId/pages

上位ページを取得

クエリパラメータ:

パラメータ型必須説明
timeRangestringいいえ期間: today、7d、30d、90d
limitintegerいいえ最大結果数 (デフォルト: 20)
リクエストBash
curl -X GET 'https://api.zenovay.com/api/external/v1/analytics/ws_abc123/pages?timeRange=7d&limit=10' \
-H 'X-API-Key: YOUR_API_KEY'
レスポンス (200 OK)JSON
{
"pages": [
  {
    "path": "/",
    "title": "Home",
    "views": 5423,
    "unique_visitors": 3241,
    "avg_time_on_page": 125,
    "bounce_rate": 0.35
  },
  {
    "path": "/pricing",
    "title": "Pricing",
    "views": 2134,
    "unique_visitors": 1876,
    "avg_time_on_page": 210,
    "bounce_rate": 0.28
  }
]
}

地理的データの取得

国別のビジターデータを取得します:

GET/api/external/v1/analytics/:websiteId/countries

地理的な内訳を取得

クエリパラメータ:

パラメータ型必須説明
timeRangestringいいえ期間: today、7d、30d、90d
リクエストBash
curl -X GET 'https://api.zenovay.com/api/external/v1/analytics/ws_abc123/countries?timeRange=30d' \
-H 'X-API-Key: YOUR_API_KEY'
レスポンス (200 OK)JSON
{
"countries": [
  {
    "code": "US",
    "name": "United States",
    "visitors": 4521,
    "percentage": 36.1
  },
  {
    "code": "GB",
    "name": "United Kingdom",
    "visitors": 1823,
    "percentage": 14.5
  },
  {
    "code": "DE",
    "name": "Germany",
    "visitors": 1456,
    "percentage": 11.6
  }
]
}

テクノロジーの内訳取得

デバイス、ブラウザ、OS の統計情報を取得します:

GET/api/external/v1/analytics/:websiteId/technology

テクノロジーの内訳を取得

クエリパラメータ:

パラメータ型必須説明
timeRangestringいいえ期間: today、7d、30d、90d
リクエストBash
curl -X GET 'https://api.zenovay.com/api/external/v1/analytics/ws_abc123/technology?timeRange=7d' \
-H 'X-API-Key: YOUR_API_KEY'
レスポンス (200 OK)JSON
{
"devices": [
  { "type": "desktop", "visitors": 7234, "percentage": 57.7 },
  { "type": "mobile", "visitors": 4521, "percentage": 36.1 },
  { "type": "tablet", "visitors": 788, "percentage": 6.3 }
],
"browsers": [
  { "name": "Chrome", "visitors": 6543, "percentage": 52.2 },
  { "name": "Safari", "visitors": 3421, "percentage": 27.3 },
  { "name": "Firefox", "visitors": 1234, "percentage": 9.8 }
],
"operating_systems": [
  { "name": "Windows", "visitors": 4521, "percentage": 36.1 },
  { "name": "macOS", "visitors": 3234, "percentage": 25.8 },
  { "name": "iOS", "visitors": 2876, "percentage": 22.9 }
]
}

高度なエンドポイント

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

ヒートマップデータを持つページを一覧表示します:

GET/api/external/v1/heatmaps/:websiteId/pages

ヒートマップページを一覧表示

リクエストBash
curl -X GET 'https://api.zenovay.com/api/external/v1/heatmaps/ws_abc123/pages' \
-H 'X-API-Key: YOUR_API_KEY'
レスポンス (200 OK)JSON
{
"pages": [
  {
    "url": "/",
    "title": "Home",
    "total_clicks": 12543,
    "total_sessions": 4521,
    "last_updated": "2025-01-20T14:30:00Z"
  },
  {
    "url": "/pricing",
    "title": "Pricing",
    "total_clicks": 8765,
    "total_sessions": 2134,
    "last_updated": "2025-01-20T14:25:00Z"
  }
]
}

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

記録されたセッションを一覧表示します:

GET/api/external/v1/replays/:websiteId/sessions

セッションリプレイを一覧表示

リクエストBash
curl -X GET 'https://api.zenovay.com/api/external/v1/replays/ws_abc123/sessions' \
-H 'X-API-Key: YOUR_API_KEY'
レスポンス (200 OK)JSON
{
"sessions": [
  {
    "session_id": "sess_abc123",
    "visitor_id": "vis_xyz789",
    "started_at": "2025-01-20T14:00:00Z",
    "duration": 245,
    "pages_visited": 5,
    "country": "US",
    "device": "desktop"
  }
],
"total": 156
}

エラーグループの取得

JavaScript エラーグループを一覧表示します:

GET/api/external/v1/errors/:websiteId/groups

エラーグループを一覧表示

リクエストBash
curl -X GET 'https://api.zenovay.com/api/external/v1/errors/ws_abc123/groups' \
-H 'X-API-Key: YOUR_API_KEY'
レスポンス (200 OK)JSON
{
"groups": [
  {
    "fingerprint": "err_abc123",
    "message": "Cannot read property 'length' of undefined",
    "type": "TypeError",
    "occurrences": 45,
    "affected_users": 23,
    "first_seen": "2025-01-15T10:00:00Z",
    "last_seen": "2025-01-20T14:30:00Z"
  }
],
"total": 12
}

Stats API (Plausible パリティ、Pro+)

Stats API は Plausible 互換の 3 つのエンドポイントをプログラムでのアナリティクスクエリに公開しています。カスタムダッシュボードの構築、BI ツールへのライブメトリクスの埋め込み、または Plausible からの最小限のコード変更での移行に使用してください。

必須プラン: Pro、Scale、または Enterprise。外部 API の残りと同様に、フリーティアのアカウントは 403 API_PAID_PLAN_REQUIRED レスポンスを受け取ります。

エンドポイント

エンドポイント目的
GET /stats/aggregate期間にわたる単一数値のメトリクス (合計、レート、期間)。
GET /stats/timeseries時間単位の系列 (日、時間、または月ごとに 1 行)。
GET /stats/breakdownグループ化されたメトリクス (上位ページ、上位国、上位ブラウザなど)。

OpenAPI 仕様: /api/external/v1/openapi.json (ライブ、公開、仕様自体の認証は不要)。

共通パラメータ

パラメータ必須説明
site_idはいウェブサイト UUID。ダッシュボード URL またはで見つけることができます GET /websites。
periodはいday、7d、30d、month、6mo、12mo、または custom:YYYY-MM-DD,YYYY-MM-DD (最大 366 日)。
dateいいえ期間の ISO 8601 基準 (デフォルト = 本日)。
metricsはいカンマ区切り。許可: visitors、pageviews、visit_duration、bounce_rate、events。
filtersいいえPlausible スタイル: country==US;browser==Chrome;page!=/admin。下記の フィルタ を参照してください。

GET /stats/aggregate

リクエストされた各メトリクスの単一数値を期間にわたって返します。

GET/api/external/v1/stats/aggregate

期間にわたるメトリクスを集計

リクエスト — 過去 7 日間のビジターとページビューBash
curl -G 'https://api.zenovay.com/api/external/v1/stats/aggregate' \
-H 'X-API-Key: YOUR_API_KEY' \
--data-urlencode 'site_id=00000000-0000-0000-0000-000000000001' \
--data-urlencode 'period=7d' \
--data-urlencode 'metrics=visitors,pageviews,bounce_rate'
レスポンス (200 OK)JSON
{
"success": true,
"data": {
  "results": {
    "visitors":    { "value": 12453 },
    "pageviews":   { "value": 38219 },
    "bounce_rate": { "value": 42.1 }
  },
  "meta": {
    "period": "7d",
    "period_start": "2026-05-07T00:00:00.000Z",
    "period_end":   "2026-05-13T23:59:59.999Z",
    "filters_applied": []
  }
},
"timestamp": "2026-05-14T08:30:00.000Z"
}

GET /stats/timeseries

期間にわたってバケットごとに 1 行を返します。デフォルト interval=day; interval=hour は period=day が必須です; interval=month は period が 6mo、12mo、month、または custom である必要があります。

GET/api/external/v1/stats/timeseries

時間単位のメトリクス系列

リクエスト — 過去 30 日間の毎日のビジター数Bash
curl -G 'https://api.zenovay.com/api/external/v1/stats/timeseries' \
-H 'X-API-Key: YOUR_API_KEY' \
--data-urlencode 'site_id=00000000-0000-0000-0000-000000000001' \
--data-urlencode 'period=30d' \
--data-urlencode 'metrics=visitors,pageviews' \
--data-urlencode 'interval=day'
レスポンス (200 OK)JSON
{
"success": true,
"data": {
  "results": [
    { "date": "2026-04-14", "visitors": 1820, "pageviews": 5640 },
    { "date": "2026-04-15", "visitors": 1933, "pageviews": 5921 }
  ],
  "meta": {
    "period": "30d",
    "interval": "day",
    "period_start": "2026-04-14T00:00:00.000Z",
    "period_end":   "2026-05-13T23:59:59.999Z",
    "filters_applied": []
  }
},
"timestamp": "2026-05-14T08:30:00.000Z"
}

レスポンスは 密集 しています — トラフィックがゼロの日でも visitors: 0 で表示されます。これにより、クライアント側のギャップ埋めなしでチャートライブラリが満足します。

GET /stats/breakdown

ディメンションでグループ化されたメトリクスをビジター降順でソートして返します。

GET/api/external/v1/stats/breakdown

グループ化されたメトリクス (上位ページ、上位国など)

リクエスト — 過去 7 日間のビジター数別上位 10 ページBash
curl -G 'https://api.zenovay.com/api/external/v1/stats/breakdown' \
-H 'X-API-Key: YOUR_API_KEY' \
--data-urlencode 'site_id=00000000-0000-0000-0000-000000000001' \
--data-urlencode 'period=7d' \
--data-urlencode 'property=event:page' \
--data-urlencode 'metrics=visitors,pageviews' \
--data-urlencode 'limit=10'
レスポンス (200 OK)JSON
{
"success": true,
"data": {
  "results": [
    { "page": "/pricing",      "visitors": 4421, "pageviews": 4421 },
    { "page": "/blog/launch",  "visitors": 2018, "pageviews": 2018 }
  ],
  "meta": {
    "period": "7d",
    "property": "event:page",
    "pagination": { "page": 1, "limit": 10, "total": 47, "has_more": true }
  }
},
"timestamp": "2026-05-14T08:30:00.000Z"
}

許可された property 値: event:page、visit:country、visit:browser、visit:device、visit:os、visit:source。

ページネーション: limit は 1 から 1000 (デフォルト 100) です; page は 1 から始まるインデックス (デフォルト 1) です。

フィルタ

Plausible スタイルのフィルタ句を ; で結合:

  • country==US — 等しい
  • country==US,CA,GB — 次のいずれかに等しい
  • browser!=Safari — 等しくない

許可されたキー: country、browser、device、os、source、utm_source、utm_medium、utm_campaign、page。

V1 制限: filters が指定されている場合、visitors メトリクスのみが計算されます; その他のメトリクスは meta.note フラグ付きで null を返します。すべてのメトリクス全体にわたるフルフィルタサポートは V2 で提供されます。

JavaScript の例

fetch() で集計メトリクスをフェッチJavaScript
async function getAggregate(siteId, period = '7d', metrics = ['visitors', 'pageviews']) {
const url = new URL('https://api.zenovay.com/api/external/v1/stats/aggregate');
url.searchParams.set('site_id', siteId);
url.searchParams.set('period', period);
url.searchParams.set('metrics', metrics.join(','));

const res = await fetch(url, {
  headers: { 'X-API-Key': process.env.ZENOVAY_API_KEY }
});
if (!res.ok) {
  const err = await res.json();
  throw new Error(`${err.error.code}: ${err.error.message}`);
}
return res.json();
}

const data = await getAggregate('00000000-0000-0000-0000-000000000001', '7d');
console.log(`Visitors: ${data.data.results.visitors.value}`);

エラーコード

Stats API は あなたが UX に優雅に対処するために切り替えることができるコードを返します:

コードHTTP時
MISSING_SITE_ID400site_id クエリパラメータが必須です。
MISSING_METRICS400metrics クエリパラメータが必須です。
MISSING_PERIOD400period クエリパラメータが必須です。
MISSING_PROPERTY400/stats/breakdown には property が必須です。
INVALID_METRIC400カンマ区切りのメトリクスの 1 つが許可リストにありません。
INVALID_PROPERTY400breakdown プロパティが許可されていません。
INVALID_PERIOD400期間が day/7d/30d/month/6mo/12mo/custom:... ではありません。
INVALID_CUSTOM_PERIOD400不正な形式の custom: 構文または無効な日付。
PERIOD_TOO_LONG400カスタム期間が 366 日を超えています。
INTERVAL_PERIOD_MISMATCH400例: interval=hour と period=7d。
UNKNOWN_FILTER_KEY400フィルタキーが許可リストにありません。
EMPTY_FILTER_VALUE400フィルタ句に値がありません。
FORBIDDEN403フリーティアアカウント (外部 API は有料プランが必須)、または site_id が API キーの範囲外です。
NOT_FOUND404サイトが存在しないか、このキーから非表示です。
(レート制限)429ティアごとのレート制限を超えました。Retry-After ヘッダーは待機時間を示します。

Plausible からの移行

パラメータ形状は意図的に Plausible 互換です:

PlausibleZenovay注釈
site_idsite_idPlausible はドメイン文字列を使用します; Zenovay は UUID を使用します。GET /websites で 1 回 domain → site_id をマップします。
period、dateperiod、date同じ許可リスト + custom:YYYY-MM-DD,YYYY-MM-DD。
metricsmetricsPlausible の visitors、pageviews、bounce_rate、visit_duration はすべて 1:1 でマップします。events は V1-近似として pageviews です。
propertyproperty同じ形状: event:page、visit:country など。
filters (v1 文字列)filters同じ key==value;key!=value 形状。JSON v2 配列フィルタは Zenovay V2 で提供されます。

JavaScript の例

JavaScript を使用してウェブサイトにアナリティクスデータを埋め込みます:

アナリティクスをフェッチして表示JavaScript
// アナリティクスデータをバックエンドからフェッチ
async function fetchAnalytics() {
const response = await fetch('/api/analytics', {
  headers: {
    'X-API-Key': 'YOUR_API_KEY' // サーバー側のプロキシを使用してキーを保護してください
  }
});

const data = await response.json();

// UI を更新
document.getElementById('live-visitors').textContent = data.live_visitors;
document.getElementById('total-pageviews').textContent = data.summary.pageviews.toLocaleString();
document.getElementById('bounce-rate').textContent = (data.summary.bounce_rate * 100).toFixed(1) + '%';
}

// 30 秒ごとに更新
fetchAnalytics();
setInterval(fetchAnalytics, 30000);

セキュリティノート: API キーをクライアント側のコードに公開しないでください。Zenovay API を呼び出すサーバー側のプロキシエンドポイントを作成し、フロントエンドがプロキシを呼び出すようにしてください。

レート制限

プランごとの外部 API レート制限:

プランリクエスト/分 (目標)月間制限 (ハードキャップ)
FreeN/A (API 利用不可)N/A
Pro3010,000
Scale60100,000
Enterprise1201,000,000

レート制限の実装方法。 1 分あたりの数字は 目標 であり、ハードシーリングではありません。Cloudflare のエッジレート制限を使用します。これは データセンターごと にバースト許容量を持つため、持続的なクライアントは、特にリクエストが複数の地域に分散される場合、見出しの数字の 1.5 倍から 3 倍を一時的に見ることがあります。ハードキャップ は月間クォータであり、リクエストを処理するエッジ POP に関係なくアカウントに対して原子的に実施されます。容量に敏感なワークロードを月間クォータに対してプラン化します。1 分あたりの目標をスムージング信号として扱ってください。

エラーレスポンス

ステータスコード説明
200成功
400不正なリクエスト - 無効なパラメータ
401未認可 - 無効または不足している API キー
403禁止 - 十分なパーミッションがありません
404見つかりません - ウェブサイトが見つかりません
429リクエストが多すぎます - レート制限を超えました
500内部サーバーエラー
エラーレスポンスの例JSON
{
"error": {
  "code": "unauthorized",
  "message": "Invalid API key provided"
}
}

次のステップ

このページは役に立ちましたか？