yandex-metrika

yandex-metrika

Работа с API Яндекс Метрики: детализация трафика по источникам и UTM-меткам, отчёты по конверсиям и поисковым системам, API-сегменты и прямые доступы к счётчикам.

Config

Требуется YANDEX_METRIKA_TOKEN в config/.env. Для чтения нужен доступ metrika:read, для создания сегментов и управления доступами — metrika:write. Инструкция: config/README.md.

Philosophy

1. Cache-first — конфигурационные данные (счётчики, цели, инфо) кешируются надолго. Отчёты кешируются по ключу counter+dates+params. Перед API-запросом всегда проверяем кеш.
2. Context window hygiene — stdout ограничен 30 строками. Полные данные в CSV/файл. Кеш доступен через grep/rg для поиска без загрузки в контекст.
3. Точные данные — accuracy=1 (без сэмплирования), фильтр isRobot по умолчанию.
4. Атрибуция — дефолт lastsign (последний значимый источник). Спрашиваем пользователя при первом запуске.

Workflow

STOP! Перед любым анализом:

1. Получи список счётчиков:

   bash scripts/counters.sh
   

2. Спроси пользователя (если счётчик не очевиден из контекста):

   "О каком счётчике/сайте идёт речь?
   Укажите ID, название или домен."
   

   Если пользователь назвал сайт/домен — ищи через --search:

   bash scripts/counters.sh --search "metallik"
   

   Это grep по TSV (id + name + site), поэтому находит и по домену.

3. Получи инфо о счётчике и его цели:

   bash scripts/counter_info.sh --counter <ID>
   bash scripts/goals.sh --counter <ID>
   

4. Спроси про конверсионные цели:

   "Какие из этих целей являются конверсионными для вашего бизнеса?
   [список целей из goals.sh]
   Сохраню выбранные для будущих отчётов."
   

5. Сохрани конфигурацию в cache/counter_<id>/config.json:

   {
     "attribution": "lastsign",
     "conversion_goals": [
       {"id": 12345, "name": "Заказ оформлен"},
       {"id": 67890, "name": "Заявка отправлена"}
     ]
   }
   

6. Запускай отчёты по задаче пользователя.

Сегменты и доступы

Для API-сегмента сначала зафиксируй понятное название и выражение filters. Создание и удаление без --apply показывают план и ничего не меняют. Перед записью сценарий читает свежую роль на счётчике; сервер API остаётся окончательным источником прав.

bash scripts/segments.sh --counter <ID> --action create \
  --name "Посетители карточек" \
  --expression "EXISTS(ym:pv:URL=@'/catalog/')"
# после проверки плана повторить с --apply

Получи точный логин от вызывающей задачи, затем проверь прямой доступ к счётчику и при необходимости подготовь минимальную роль:

bash scripts/grants.sh --counter <ID> --action get --login <LOGIN>
bash scripts/grants.sh --counter <ID> --action add \
  --login <LOGIN> --permission view
# после проверки плана повторить с --apply

Для использования сегмента обычно достаточно view. Не выдавай edit, если задача не требует менять счётчик. Если пользователь выбрал analyst или edit, передай эту роль через --permission; существующую роль меняй через update. Список /grants содержит прямые разрешения; владелец выводится отдельно, а представители аккаунта в этот список не входят. После записи верни вызывающей задаче номер счётчика, ID сегмента, логин и подтверждённую роль. Подробности: API-сегменты и прямые доступы к счётчику.

Scripts

Общий паттерн вызова:

bash scripts/<script>.sh --counter <ID> --date1 YYYY-MM-DD [--date2 ...] [--group month] [--csv path]

Script	Description	Special params
counters.sh	Список счётчиков	--search "query"
goals.sh	Цели счётчика	—
counter_info.sh	Метаданные счётчика	—
traffic_summary.sh	Трафик по источникам	—
conversions.sh	Достижение целей	--goals "ID,ID" / --all-goals; по умолчанию из config.json
utm_report.sh	UTM-разбивка	—
search_engines.sh	Поисковые системы (organic)	—
ecommerce.sh	Покупки, выручка, средний чек	--currency RUB|USD|EUR; авто из counter_info
direct_clients.sh	Логины Директа	—
direct_costs.sh	Расходы Директа (ym:ad:*)	--direct-client-logins "login"; нет --group/--device/--source
comparison.sh	Сравнение двух периодов	--date1a/--date2a/--date1b/--date2b; --dimension, --metrics
segments.sh	Список, просмотр, создание и удаление API-сегментов	--action; запись только с --apply
grants.sh	Владелец и прямые доступы по логинам; роли view, analyst, edit	--action; запись только с --apply

Не все скрипты поддерживают все общие параметры — см. Special params. Сценариям управления segments.sh и grants.sh для надёжного разбора JSON нужен Python 3.10+ либо uv; обычные отчёты по-прежнему работают без них.

目標レポート

conversions.sh は目標を6件ずつ自動的に取得し、1つのCSVにまとめます。--all-goals、--goals、および config.json の目標で動作します。 --all-goals の場合は、最初にManagement APIを使って目標リストを更新します。 結合には通常の awk を使用するため、レポートの実行にPythonや uv は必要ありません。 目標ごとに、達成を含む訪問数、達成数、コンバージョン率の3つの指標が保存されます。 列に表示される目標の順序は、選択したリストの順序と一致します。

達成数が0の流入元が個別の取得結果から消えないよう、リクエストには訪問数の総指標を追加します。最終CSVには内部処理用の指標は含まれませんが、コンバージョンのない流入元は保持され、最終的なコンバージョン率にはその訪問数が反映されます。 流入元は、最初に選択した目標の達成を含む訪問数で並べ替え、同数の場合は流入元で並べ替えます。

--limit は流入元の件数を制限します。--group を指定しない場合は1～100000件（デフォルトは100件）、--group を指定する場合は1～30件（デフォルトは30件、APIパラメーターは top_keys）です。 日付の範囲は短縮されません。すべての取得結果の受信と結合が正常に完了した場合にのみ、レポートがキャッシュに保存され、--csv に出力されます。

レポートスクリプト共通のパラメーター

パラメーター	必須	デフォルト	値
--counter	はい	-	カウンターID
--date1	はい	-	YYYY-MM-DD
--date2	いいえ	今日	YYYY-MM-DD
--group	いいえ	-	day、week、month
--device	いいえ	all	desktop、mobile、tablet
--source	いいえ	all	organic、ad、referral、direct、social
--attribution	いいえ	lastsign	lastsign、last、first
--filters	いいえ	ロボットを除外	レポートAPIのセグメント条件式
--limit	いいえ	APIのデフォルト	行数
--csv	いいえ	-	エクスポート先のパス
--no-cache	いいえ	-	キャッシュをスキップ

キャッシュ戦略

キャッシュは cache/ に保存されます。

• counters.json + counters.tsv — すべてのカウンター
• counter_<id>/info.json — メタデータ（永続）
• counter_<id>/goals.json + goals.tsv — 目標
• counter_<id>/config.json — アトリビューション、コンバージョン目標
• counter_<id>/direct_clients.json — Directのログイン情報
• counter_<id>/reports/*.csv — レポート結果

セグメントとアクセス権は毎回読み込み直され、キャッシュには保存されません。これらのデータはレポートとは別に変更され、アクセス権のリストにはユーザーのログイン情報が含まれるためです。

キャッシュ内を検索するには、grep "text" cache/counters.tsv または rg "text" cache/ を使用します。

応用シナリオ

• 人気の検索クエリ
• 任意のレポートとJSONリクエスト（drilldown、metrika_getなど）
• dimensions/metricsリファレンス
• 前年同期との期間比較
• Directの費用とPnL
• Directでのオーディエンス選定用APIセグメント
• 広告アカウントのアクセス権の確認と付与
• APIの制限（bytime、scope mixing、drilldown CSV）

APIの制限

• Reporting API：約200リクエスト／5分（上限を超えた場合は約5分待ちます）
• スクリプトは429を自動的に処理します（Retry-After ≤ 60sの場合は再試行、それ以外はメッセージを表示して失敗します）