Download the PHP package jsonseo/php-sdk without Composer

JSON SEO PHP SDK

Официальный PHP-клиент JSON SEO API: выдача Яндекса, Google и Bing, картинки и видео, поисковые подсказки, Яндекс Вордстат, прогноз показов Директа и геолокация по IP.

• Работает на PHP 7.1 и выше, включая 8.5.
• Без зависимостей: ходит через ext-curl, а где его нет — через потоки PHP.
• Двадцать один метод сервиса.
• Три попытки на запрос по умолчанию: если сервис затупил, SDK сходит ещё раз сам.

Установка

Ключ берётся в личном кабинете.

Быстрый старт

Если у метода один обязательный параметр, его можно передать просто строкой:

Примеры запросов

Позиции сайта в Яндексе

break_domain останавливает сбор на нужном домене — платить за страницы ниже найденной позиции незачем.

В ответе:

Выдача Google по нужному городу

Регион задаётся числовым ID из справочника — сервис сам соберёт uule и подставит gl.

Если Google схлопнул часть результатов как «очень похожие», причина придёт в filter_description, а вернуть их можно параметром filter:

Выдача Bing

Реклама на странице выдачи

Приходит отдельным массивом, органика не меняется. Стоит +0.01 ₽ за страницу, на которой реклама нашлась.

block — где стоял блок: top до органики, bottom после неё, inline между результатами. Пустой массив ads значит «рекламу просили, но её не было», а отсутствие поля — «не просили».

Ответ нейросети над выдачей

Стоит +0.01 ₽ и только когда ответ есть: если поисковик его не показал, запрос обойдётся в обычную цену. Доступен только с первой страницы.

Картинки

Те же параметры работают у googleImages() и bingImages() — SDK переводит общий фильтр в родной параметр движка. Если у поисковика такого значения нет, придёт ошибка 422 с указанием, чем заменить.

Видео

Поле duration приходит в секундах, но не всегда: у прямых эфиров вместо длины стоит LIVE. Отбор вида duration < 600 молча выбросит такие ролики — ориентируйтесь на durationText, он на месте всегда.

Поисковые подсказки

Есть у всех трёх поисковиков: yandexSuggest(), googleSuggest(), bingSuggest().

Справочник регионов

Бесплатно, но ключ нужен: по нему считается лимит запросов в минуту. У googleRegions() в ответе дополнительно приходит готовая строка uule.

Вордстат: частота запроса

Вид частотности задаётся параметром kind, кавычки и операторы расставит сервис — фразу передавайте как есть:

Вордстат: расширение семантики

popular — что ищут вместе с фразой, associations — соседняя семантика.

Вордстат: сезонность

month и week отдают историю с 2018 года, day — последние 60 дней.

Вордстат: география спроса

popularity — affinity-индекс: 100 означает средний по стране интерес, выше — повышенный. В каждой строке приходит region_id, его можно сразу подставить в region других методов.

Прогноз показов Яндекс Директа

Рекламный кабинет не нужен. Список фраз передаётся массивом — SDK склеит его сам.

Вид частотности задаётся операторами прямо во фразе: ремонт айфона — базовая, "ремонт айфона" — фразовая, "!ремонт !айфона" — точная.

Стоимость — 0.01 ₽ за пачку до 4000 символов, это около 150 обычных фраз. За один запрос принимается до 1000 фраз, на аккаунт — не больше 100 запросов в час.

Геолокация по IP

ID региона тот же, что у Яндекса, — его можно сразу подставить в region методов выдачи и Вордстата:

Баланс

Справочник методов

Полный список параметров каждого метода — в документации и в PHPDoc самих методов: IDE подскажет имена прямо на месте вызова.

Появился метод, которого ещё нет в SDK? Его можно вызвать напрямую:

Как SDK помогает с параметрами

Списки передаются массивами. Фразы для Директа склеиваются переводом строки, остальные списки — запятой:

Флаги принимаются флагами. true и false уезжают как 1 и 0:

null и пустой массив не отправляются. Необязательный параметр, который вы ещё не посчитали, можно не вычищать из массива руками.

Ошибки

Всё, что бросает SDK, наследуется от JsonSeo\Exception\JsonSeoException.

У всех отказов сервиса есть status(), body(), разобранный payload() и retryAfter() — срок, который назвал сервис, если он его назвал.

Повторы

У каждого запроса три попытки по умолчанию: одна основная и две повторных. Если сервис затупил и выдачу собрать не вышло (503), SDK сам сходит ещё дважды, и обычно этого хватает.

429, 5xx и обрывы связи повторяются автоматически — это ровно те отказы, за которые сервис денег не берёт. Отказы по ключу, балансу и параметрам не повторяются: сами они не изменятся.

Таймаут и оборвавшееся посреди тела соединение не повторяются, и это намеренно: работу на стороне сервиса обрыв у клиента не отменяет — выдача будет собрана и оплачена, а повтор стоил бы ещё раз. Если ответ не успевает прийти, поднимайте timeout, а не attempts.

Пауза между попытками удваивается и разбавляется случайной добавкой. Если сервис прислал Retry-After, SDK не вернётся раньше названного срока. Когда сервис просит ждать дольше max_retry_delay, SDK не ждёт вовсе, а отдаёт исключение с retryAfter() — решение остаётся за вами.

'attempts' => 1 отключает повторы совсем.

Настройки клиента

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

Ключ по умолчанию едет в заголовке Authorization: Bearer, а не в адресе: так он не оседает в логах прокси и серверов. AUTH_QUERY нужен там, где заголовки до API не доходят.

Свой транспорт

Если HTTP в проекте уже ходит через Guzzle, Symfony HttpClient или что-то своё, SDK можно отдать этот клиент — достаточно объекта с одним методом:

Тот же приём годится для тестов: подмените транспорт заглушкой, и запросы никуда не пойдут.

Разработка

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

Лицензия

MIT.