Формат JSON
Взаимодействие с API Яндекс Директа в формате JSON.
Преимущество JSON в большей компактности по сравнению с SOAP/XML, а также в скорости анализа запросов на стороне Яндекс Директа.
Во многих языках программирования существуют модули и библиотеки для работы с JSON. Ниже перечислены рекомендуемые модули и библиотеки для популярных языков.
- Perl: модуль JSON.
- PHP: встроенная поддержка JSON началась в версии 5.2.0. В предыдущих версиях можно использовать библиотеку Services_JSON.
- Python: модуль json.
Запросы JSON
Запросы в формате JSON передаются методом HTTP POST на следующий адрес:
Версия 4
https://api.direct.yandex.ru/v4/json/
Версия Live 4
https://api.direct.yandex.ru/live/v4/json/
Запрос всегда содержит ключ method с именем вызываемого метода и в большинстве случаев ключ param (см. пример ниже). Некоторые методы не имеют входных параметров, и для них ключ param не требуется.
Пример запроса JSON
Пример демонстрирует вызов метода GetClientInfo. В ключе param передается массив из одной строки, которая является логином пользователя. Ключ locale устанавливает русский язык для ответных сообщений. Ключ token — авторизационный токен, выданный OAuth-сервером Яндекса с согласия пользователя (подробнее см. Авторизационные токены).
POST /v4/json/ HTTP/1.1
Host: api.direct.yandex.ru
Content-Length: 204
Content-Type: application/json; charset=utf-8
{
"method": "GetClientInfo",
"param": ["agrom"],
"locale": "ru",
"token": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f"
}
Язык ответных сообщений
Запрос может содержать ключ locale, указывающий язык ответных сообщений. На выбранном языке возвращаются статусы кампаний, статусы баннеров и сообщения об ошибках. Возможны следующие значения locale:
- ru — русский;
- en — английский.
Если ключ locale отсутствует, подразумевается английский язык.
Сообщения об ошибках
При возникновении ошибок обработка запроса прекращается и возвращается сообщение об ошибке в формате JSON. Пример сообщения показан ниже.
{
"error_detail":"Метод HTTP запроса должен быть POST",
"error_str":"Неверный метод запроса",
"error_code":512
}
Параметр error_code содержит код ошибки, error_str — краткое описание ошибки, error_detail — дополнительные пояснения, если имеются. Краткое описание и дополнительное пояснение могут выводиться на разных языках, что определяется параметром locale, указанным при вызове метода.