yandex-metrica

yandex-metrica

Yandex Metrica API — ウェブ分析：カウンター、レポート、目標、ログのエクスポート。

設定

config/.env に YANDEX_METRICA_TOKEN が必要です。 トークンの設定（OAuth、権限：metrika:read、metrika:write）については、config/README.md を参照してください。

クイックスタート

重要： スクリプトは必ず bash を先頭に付け、スキルディレクトリからの絶対パスで実行してください。スクリプトは bash 固有の機能を使用しているため、zsh から読み込んでも動作しません。scripts/common.sh を直接 source しないでください。以下のラッパースクリプトを使用してください。

# 1. Setup token
bash scripts/get_token.sh --client-id YOUR_CLIENT_ID

# 2. Check connection
bash scripts/check_connection.sh

# 3. List counters
bash scripts/counters.sh --action list

# 4. Get traffic stats
bash scripts/stats.sh --counter 12345678 --preset traffic

# 5. Export raw logs
bash scripts/logs.sh --action create --counter 12345678 --date1 2025-01-01 --date2 2025-01-31

API の概要

ベース URL：https://api-metrika.yandex.net

認証ヘッダー：Authorization: OAuth TOKEN

API	用途	ベースパス
Management	カウンター、目標、フィルター、権限付与、セグメント	/management/v1/
Reporting	集計統計、ディメンション、指標	/stat/v1/
Logs	生の訪問／ヒットデータのエクスポート	/management/v1/counter/{id}/logrequests

スクリプト

check_connection.sh

API トークンを確認し、利用可能なカウンターを一覧表示します。

bash scripts/check_connection.sh

counters.sh

カウンターを管理します：一覧表示、詳細の取得、目標やフィルターを含む全情報の取得。

bash scripts/counters.sh --action list
bash scripts/counters.sh --action list --search "mysite.com"
bash scripts/counters.sh --action info --counter 12345678

stats.sh

プリセット、またはカスタムの指標／ディメンションを使ってレポートデータを取得します。

# Traffic overview
bash scripts/stats.sh --counter 12345678 --preset traffic

# Traffic sources breakdown
bash scripts/stats.sh --counter 12345678 --preset sources

# Top pages
bash scripts/stats.sh --counter 12345678 --preset content

# Custom report with filters
bash scripts/stats.sh --counter 12345678 \
  --metrics "ym:s:visits,ym:s:users,ym:s:bounceRate" \
  --dimensions "ym:s:lastTrafficSource" \
  --filters "ym:s:trafficSource=='organic'" \
  --date1 2025-01-01 --date2 2025-01-31

# Time-series report
bash scripts/stats.sh --counter 12345678 --type bytime \
  --metrics "ym:s:visits" --date1 2025-01-01 --date2 2025-01-31

# Export to CSV
bash scripts/stats.sh --counter 12345678 --preset sources --csv report.csv

パラメーター	デフォルト	説明
--counter	環境変数	カウンター ID（必須）
--metrics	visits,pageviews,users	カンマ区切りの指標
--dimensions	—	カンマ区切りのディメンション
--date1	30日前	開始日 YYYY-MM-DD
--date2	今日	終了日 YYYY-MM-DD
--filters	—	フィルター式
--sort	—	ソートするフィールド（降順の場合は先頭に - を付けます）
--limit	100	最大行数
--preset	—	traffic、sources、geo、content、technology
--type	data	data、bytime、drilldown、comparison
--csv	—	CSV ファイルにエクスポート

goals.sh

カウンターの目標を一覧表示し、取得します。

bash scripts/goals.sh --action list --counter 12345678
bash scripts/goals.sh --action get --counter 12345678 --goal-id 999

logs.sh

Logs API を使って生データをエクスポートします。

# Check if export is possible
bash scripts/logs.sh --action evaluate --counter 12345678 \
  --date1 2025-01-01 --date2 2025-01-31

# Create log request
bash scripts/logs.sh --action create --counter 12345678 \
  --source visits --date1 2025-01-01 --date2 2025-01-31

# Check status
bash scripts/logs.sh --action status --counter 12345678 --request-id 777

# Download when ready
bash scripts/logs.sh --action download --counter 12345678 \
  --request-id 777 --output ./exports

# Clean up server-side
bash scripts/logs.sh --action clean --counter 12345678 --request-id 777

# List all log requests
bash scripts/logs.sh --action list --counter 12345678

主要指標のクイックリファレンス

指標	説明
ym:s:visits	セッション数
ym:s:users	ユニーク訪問者数
ym:s:pageviews	ページビュー数
ym:s:bounceRate	直帰率（％）
ym:s:avgVisitDurationSeconds	平均セッション時間
ym:s:newUsers	新規訪問者数
ym:s:goal<ID>reaches	目標達成数
ym:s:goal<ID>conversionRate	目標コンバージョン率
ym:s:ecommerceRevenue	E コマース収益

主要ディメンションのクイックリファレンス

ディメンション	説明
ym:s:trafficSource	トラフィックソースの種類
ym:s:lastTrafficSource	最後のトラフィックソース
ym:s:<attr>UTMSource	UTM ソース
ym:s:<attr>UTMMedium	UTM メディア
ym:s:startURL	ランディングページ
ym:s:regionCountry	国
ym:s:regionCity	都市
ym:s:browser	ブラウザー
ym:s:deviceCategory	デバイスの種類
ym:s:operatingSystem	OS

<attr> = アトリビューションモデル：last、first、lastsign など。

フィルター構文

ym:s:trafficSource=='organic'           # equals
ym:s:trafficSource!='organic'           # not equals
ym:s:trafficSource=.('organic','direct') # in list
ym:s:pageViews>5                        # greater than
ym:s:startURL=@'product'               # contains
ym:s:startURL=~'.*product.*'           # regex
ym:s:trafficSource=='organic' AND ym:s:isRobot=='No'  # combine

レート制限

制限	値
一般 API	IP あたり 30 リクエスト／秒
Logs API	IP あたり 10 リクエスト／秒
並列リクエスト	ユーザーあたり 3
1 日あたりの上限	5,000 リクエスト／日
Reports API	5 分あたり 200 リクエスト

詳細リファレンス

すべてのエンドポイント、フィールド一覧、curl の例、高度な機能を含む包括的な API ドキュメントについては、以下を参照してください： references/api-reference.md

対象：Management API（カウンター、目標、フィルター、操作、権限付与、ラベル、セグメント、ユーザーパラメーター）、Reporting API（data、bytime、drilldown、comparison、プリセット、すべての指標／ディメンション）、Logs API（訪問／ヒットのフィールド）。