Прогноз Директа списком фраз: в сто раз дешевле, чем по одной

Прогноз показов Яндекс Директа тарифицируется не по фразам, а по пачкам: одна пачка - 0.01 ₽, и в неё помещается до 4000 символов фраз. Разница между «отправил фразу» и «отправил список» получается стократной, причём в буквальном смысле: сто фраз по одной стоят 1 ₽, те же сто фраз списком - 0.01 ₽.

При этом резать список на пачки самому не нужно. Вы отправляете фразы как есть, а разбивка по 4000 символов, дедупликация и сборка ответа - наша работа.

Сколько это стоит

Сколько фраз влезет в пачку, зависит от их длины. Считаем по фразе из трёх-четырёх слов - это 26 символов вместе с разделителем, то есть около 150 фраз в пачке. Отсюда и счёт:

Числа в колонке «списком» - расчётные, под ту же фразу в 26 символов. Длина фраз на них влияет прямо: при 30 символах тысяча фраз займёт уже 8 пачек вместо 7, то есть 0.08 ₽. Короткие однословные запросы, наоборот, укладываются плотнее. Порядок величины от этого не меняется - разница с оплатой по одной фразе остаётся стократной.

Как передать список

Параметр phrases принимает фразы через запятую или с новой строки - как удобнее. Можно и массивом: phrases[]=... в форме или JSON-массив строк в теле. Ограничение одно: не больше 1000 фраз за вызов.

Метод - POST. В адресной строке помещается около 65 000 байт, кириллица кодируется втрое длиннее, и примерно с 500 русских фраз список туда перестаёт помещаться. Отказ при этом невнятный: соединение обрывается без кода ошибки и без тела ответа. У тела предел выше - 2 МиБ, поэтому длинные списки отправляйте POST сразу, не дожидаясь границы.

curl -X POST "https://jsonseo.ru/api/direct" \
  -d "key=ВАШ_КЛЮЧ" \
  -d "region=225" \
  -d "period=month" \
  -d "phrases=купить окна пвх,установка окон москва,пластиковые окна цена"

В ответе - строка на каждую фразу и сводка по пачкам:

{
    "geo": 225,
    "period": "month",
    "batches": 1,
    "processed": 1,
    "results": [
        { "phrase": "купить окна пвх", "shows": 12345, "positions": { ... } }
    ],
    "errors": []
}

Списки длиннее тысячи фраз бьются на вызовы по 1000 - это единственное место, где деление остаётся за вами. Внутри вызова всё остальное берём на себя.

Что делаем за вас

Собираем пачки. Фразы сортируются и укладываются в пачки по 4000 символов так, чтобы пачек вышло как можно меньше - вы платите ровно за столько, сколько получилось.

Убираем дубли. Повторы в списке схлопываются до отправки, поэтому за одну и ту же фразу дважды платить не придётся. Заодно фразы приводятся к единому виду: лишние пробелы убираются, регистр опускается, «ё» приводится к «е».

Считаем деньги по факту. Списывается столько пачек, сколько реально обработано - их число лежит в поле processed. Если на середине списка закончился баланс или что-то не заладилось, за необработанный остаток деньги возвращаются, а processed окажется меньше batches - по этому расхождению неполный прогноз и видно.

Почему это важно не только вам

Экономия здесь взаимная, и это не фигура речи. Прогноз считает Яндекс, и его сторона ограничивает не количество фраз, а количество обращений. Сто фраз одной пачкой - это одно обращение; те же сто фраз по одной - сто обращений за тем же самым результатом.

Для нас разница между этими двумя способами - разница между спокойной работой метода и его отказами. Когда кто-то один начинает ходить по фразе за раз, лимиты на стороне Яндекса выбираются быстро, и ошибки достаются всем, кто в этот момент работает с прогнозом, включая самого автора нагрузки. Поэтому список - не просто дешевле, а ещё и надёжнее: он реже упирается в отказ.

Ограничение на число запросов

Чтобы этот сценарий не ломал метод остальным, число запросов ограничено: не больше 100 в час на аккаунт. Считаются именно запросы, а не фразы.

Разница принципиальная. Сто запросов по одной фразе - это сто фраз в час. Сто запросов по тысяче фраз - это сто тысяч фраз в час, примерно за 7 ₽. Лимит ничего не отнимает у того, кто собирает список; он мешает только дробить работу на мелкие вызовы.

Если лимит исчерпан, метод отвечает 429. Собрать список в этот момент уже не поможет - счётчик считает запросы, и следующий получит тот же отказ. Придётся ждать: окно отсчитывается от первого запроса, а не по календарным часам, так что ожидание может дойти до часа - верхнюю границу метод называет заголовком Retry-After. Поэтому складывать фразы в список нужно заранее, а не после первого отказа.

Частые вопросы

Считается запрос или пачка?

Запрос - то есть одно обращение к API. Если в нём тысяча фраз, которые разложились на семь пачек, счётчик увеличится на единицу, а не на семь. Деньги при этом списываются за пачки: в этом примере 0.07 ₽.

Список стал длиннее 4000 символов - что будет?

Ничего особенного: он разложится на несколько пачек, и в ответе это будет видно в поле batches. Отдельно ограничена только длина одной фразы - те же 4000 символов, но в такую длину ни одна осмысленная фраза не упирается.

Можно ли считать прогноз по нескольким регионам сразу?

Регионы перечисляются в region через запятую, а минус перед ID исключает регион вместе со всем, что в него входит: region=3,-1 - Центральный федеральный округ без Москвы и области, region=225,-213 - Россия без Москвы. Списком считается один прогноз, а не несколько: это тот же один запрос и те же пачки. Регионы тоже можно передать массивом - region[]=3&region[]=-1.

Вернуть вычтенное обратно вложенным ID нельзя: 3,-1,213 даёт то же, что 3,-1, Москва обратно не добавится. Это правило самого Директа.

Можно ли слать списки параллельно?

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

А через MCP?

Так же: у инструмента direct_forecast на MCP-сервере тот же параметр со списком фраз, и то же правило - одним списком дешевле. Подключение разобрано в инструкции по MCP.

Чем прогноз отличается от частотности Вордстата?

Вордстат говорит о прошлых запросах, прогноз - об ожидаемых показах рекламы с поправкой на сезон. Подробнее - в статье про прогноз бюджета Яндекс Директа, а полное описание параметров метода - в документации.