yandex-metrika
Работа с Yandex Metrika Reporting API v1. Отчёты по трафику, конверсиям, UTM-меткам, поисковым системам.
Config
Требуется YANDEX_METRIKA_TOKEN в config/.env.
Инструкция: config/README.md.
Philosophy
- Cache-first — конфигурационные данные (счётчики, цели, инфо) кешируются надолго. Отчёты кешируются по ключу counter+dates+params. Перед API-запросом всегда проверяем кеш.
- Context window hygiene — stdout ограничен 30 строками. Полные данные в CSV/файл. Кеш доступен через grep/rg для поиска без загрузки в контекст.
- Точные данные — accuracy=1 (без сэмплирования), фильтр isRobot по умолчанию.
- Атрибуция — дефолт
lastsign (последний значимый источник). Спрашиваем пользователя при первом запуске.
Workflow
STOP! Перед любым анализом:
Получи список счётчиков:
bash scripts/counters.sh
Спроси пользователя (если счётчик не очевиден из контекста):
"О каком счётчике/сайте идёт речь?
Укажите ID, название или домен."
Если пользователь назвал сайт/домен — ищи через --search:
bash scripts/counters.sh --search "metallik"
Это grep по TSV (id + name + site), поэтому находит и по домену.
Получи инфо о счётчике и его цели:
bash scripts/counter_info.sh --counter <ID>
bash scripts/goals.sh --counter <ID>
Спроси про конверсионные цели:
"Какие из этих целей являются конверсионными для вашего бизнеса?
[список целей из goals.sh]
Сохраню выбранные для будущих отчётов."
Сохрани конфигурацию в cache/counter_<id>/config.json:
{
"attribution": "lastsign",
"conversion_goals": [
{"id": 12345, "name": "Заказ оформлен"},
{"id": 67890, "name": "Заявка отправлена"}
]
}
Запускай отчёты по задаче пользователя.
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 |
Не все скрипты поддерживают все общие параметры — см. Special params.
Отчёт по целям
conversions.sh автоматически запрашивает цели частями по шесть и объединяет их
в один CSV. Это работает для --all-goals, --goals и целей из config.json.
При --all-goals список целей сначала обновляется через Management API.
Объединение выполняется обычным awk; для запуска отчётов Python и uv не нужны.
На каждую цель сохраняются три метрики: визиты с достижением, достижения и конверсия.
Порядок целей в колонках соответствует выбранному списку.
В запросы добавляется общий показатель визитов, чтобы источники с нулевыми
достижениями не исчезали из отдельных частей. В итоговом CSV служебных метрик нет,
но источники без конверсий сохраняются; итоговая конверсия учитывает их визиты.
Источники сортируются по визитам с достижением первой выбранной цели,
при равенстве — по источнику.
--limit ограничивает число источников: без --group допустимо 1–100000
(по умолчанию 100); с --group — 1–30 (по умолчанию 30, параметр API top_keys).
Даты при этом не сокращаются. Отчёт попадает в кеш и --csv только после
успешного получения и объединения всех частей.
Общие параметры отчётных скриптов
| Param |
Required |
Default |
Values |
--counter |
yes |
- |
ID счётчика |
--date1 |
yes |
- |
YYYY-MM-DD |
--date2 |
no |
today |
YYYY-MM-DD |
--group |
no |
- |
day, week, month |
--device |
no |
all |
desktop, mobile, tablet |
--source |
no |
all |
organic, ad, referral, direct, social |
--attribution |
no |
lastsign |
lastsign, last, first |
--limit |
no |
API default |
число строк |
--csv |
no |
- |
путь для экспорта |
--no-cache |
no |
- |
пропустить кеш |
Кеш-стратегия
Кеш хранится в cache/:
counters.json + counters.tsv — все счётчики
counter_<id>/info.json — метаданные (permanent)
counter_<id>/goals.json + goals.tsv — цели
counter_<id>/config.json — атрибуция, конверсионные цели
counter_<id>/direct_clients.json — логины Директа
counter_<id>/reports/*.csv — результаты отчётов
Для поиска по кешу: grep "text" cache/counters.tsv или rg "text" cache/.
Расширенные сценарии
- Популярные поисковые запросы
- Произвольные отчёты и JSON-запросы (drilldown, metrika_get и др.)
- Справочник dimensions/metrics
- Сравнение периодов год-к-году
- Расходы Директа и PnL
- Ограничения API (bytime, scope mixing, drilldown CSV)
Лимиты API
- Reporting API: ~200 запросов / 5 минут (при превышении — ждите ~5 минут)
- Скрипты автоматически обрабатывают 429 (Retry-After ≤ 60s → retry, иначе fail с сообщением)
1---2name: yandex-metrika3description: |4 Аналитика Yandex Metrika: трафик, конверсии, UTM, поисковые системы.5 Cache-first подход для гигиены контекстного окна.6 Triggers: яндекс метрика, yandex metrika, metrika analytics,7 метрика трафик, метрика конверсии, метрика отчёт.8metadata:9 source: https://skillmd.com/skills/artwist-polyakov/yandex-metrika10---1112# yandex-metrika1314Работа с Yandex Metrika Reporting API v1. Отчёты по трафику, конверсиям, UTM-меткам, поисковым системам.1516## Config1718Требуется `YANDEX_METRIKA_TOKEN` в `config/.env`.19Инструкция: `config/README.md`.2021## Philosophy22231. **Cache-first** — конфигурационные данные (счётчики, цели, инфо) кешируются надолго. Отчёты кешируются по ключу counter+dates+params. Перед API-запросом всегда проверяем кеш.242. **Context window hygiene** — stdout ограничен 30 строками. Полные данные в CSV/файл. Кеш доступен через grep/rg для поиска без загрузки в контекст.253. **Точные данные** — accuracy=1 (без сэмплирования), фильтр isRobot по умолчанию.264. **Атрибуция** — дефолт `lastsign` (последний значимый источник). Спрашиваем пользователя при первом запуске.2728## Workflow2930### STOP! Перед любым анализом:31321. **Получи список счётчиков:**33 ```bash34 bash scripts/counters.sh35 ```36372. **Спроси пользователя** (если счётчик не очевиден из контекста):38 ```39 "О каком счётчике/сайте идёт речь?40 Укажите ID, название или домен."41 ```42 Если пользователь назвал сайт/домен — ищи через `--search`:43 ```bash44 bash scripts/counters.sh --search "metallik"45 ```46 Это grep по TSV (id + name + site), поэтому находит и по домену.47483. **Получи инфо о счётчике и его цели:**49 ```bash50 bash scripts/counter_info.sh --counter <ID>51 bash scripts/goals.sh --counter <ID>52 ```53544. **Спроси про конверсионные цели:**55 ```56 "Какие из этих целей являются конверсионными для вашего бизнеса?57 [список целей из goals.sh]58 Сохраню выбранные для будущих отчётов."59 ```60615. **Сохрани конфигурацию** в `cache/counter_<id>/config.json`:62 ```json63 {64 "attribution": "lastsign",65 "conversion_goals": [66 {"id": 12345, "name": "Заказ оформлен"},67 {"id": 67890, "name": "Заявка отправлена"}68 ]69 }70 ```71726. **Запускай отчёты** по задаче пользователя.7374## Scripts7576Общий паттерн вызова:77```bash78bash scripts/<script>.sh --counter <ID> --date1 YYYY-MM-DD [--date2 ...] [--group month] [--csv path]79```8081| Script | Description | Special params |82|--------|-------------|----------------|83| `counters.sh` | Список счётчиков | `--search "query"` |84| `goals.sh` | Цели счётчика | — |85| `counter_info.sh` | Метаданные счётчика | — |86| `traffic_summary.sh` | Трафик по источникам | — |87| `conversions.sh` | Достижение целей | `--goals "ID,ID"` / `--all-goals`; по умолчанию из `config.json` |88| `utm_report.sh` | UTM-разбивка | — |89| `search_engines.sh` | Поисковые системы (organic) | — |90| `ecommerce.sh` | Покупки, выручка, средний чек | `--currency RUB\|USD\|EUR`; авто из counter_info |91| `direct_clients.sh` | Логины Директа | — |92| `direct_costs.sh` | Расходы Директа (`ym:ad:*`) | `--direct-client-logins "login"`; нет `--group`/`--device`/`--source` |93| `comparison.sh` | Сравнение двух периодов | `--date1a/--date2a/--date1b/--date2b`; `--dimension`, `--metrics` |9495Не все скрипты поддерживают все общие параметры — см. **Special params**.9697### Отчёт по целям9899`conversions.sh` автоматически запрашивает цели частями по шесть и объединяет их100в один CSV. Это работает для `--all-goals`, `--goals` и целей из `config.json`.101При `--all-goals` список целей сначала обновляется через Management API.102Объединение выполняется обычным `awk`; для запуска отчётов Python и `uv` не нужны.103На каждую цель сохраняются три метрики: визиты с достижением, достижения и конверсия.104Порядок целей в колонках соответствует выбранному списку.105106В запросы добавляется общий показатель визитов, чтобы источники с нулевыми107достижениями не исчезали из отдельных частей. В итоговом CSV служебных метрик нет,108но источники без конверсий сохраняются; итоговая конверсия учитывает их визиты.109Источники сортируются по визитам с достижением первой выбранной цели,110при равенстве — по источнику.111112`--limit` ограничивает число источников: без `--group` допустимо 1–100000113(по умолчанию 100); с `--group` — 1–30 (по умолчанию 30, параметр API `top_keys`).114Даты при этом не сокращаются. Отчёт попадает в кеш и `--csv` только после115успешного получения и объединения всех частей.116117## Общие параметры отчётных скриптов118119| Param | Required | Default | Values |120|-------|----------|---------|--------|121| `--counter` | yes | - | ID счётчика |122| `--date1` | yes | - | YYYY-MM-DD |123| `--date2` | no | today | YYYY-MM-DD |124| `--group` | no | - | day, week, month |125| `--device` | no | all | desktop, mobile, tablet |126| `--source` | no | all | organic, ad, referral, direct, social |127| `--attribution` | no | lastsign | lastsign, last, first |128| `--limit` | no | API default | число строк |129| `--csv` | no | - | путь для экспорта |130| `--no-cache` | no | - | пропустить кеш |131132## Кеш-стратегия133134Кеш хранится в `cache/`:135- `counters.json` + `counters.tsv` — все счётчики136- `counter_<id>/info.json` — метаданные (permanent)137- `counter_<id>/goals.json` + `goals.tsv` — цели138- `counter_<id>/config.json` — атрибуция, конверсионные цели139- `counter_<id>/direct_clients.json` — логины Директа140- `counter_<id>/reports/*.csv` — результаты отчётов141142Для поиска по кешу: `grep "text" cache/counters.tsv` или `rg "text" cache/`.143144## Расширенные сценарии145146- [Популярные поисковые запросы](references/SEARCH_QUERIES.md)147- [Произвольные отчёты и JSON-запросы](references/CUSTOM_REPORTS.md) (drilldown, metrika_get и др.)148- [Справочник dimensions/metrics](references/API_REFERENCE.md)149- [Сравнение периодов год-к-году](references/PERIOD_COMPARISON.md)150- [Расходы Директа и PnL](references/DIRECT_COSTS.md)151- [Ограничения API](references/API_REFERENCE.md#known-api-limitations) (bytime, scope mixing, drilldown CSV)152153## Лимиты API154155- **Reporting API**: ~200 запросов / 5 минут (при превышении — ждите ~5 минут)156- Скрипты автоматически обрабатывают 429 (Retry-After ≤ 60s → retry, иначе fail с сообщением)