JSON format
Accessing the Yandex Direct API in JSON format.
The advantage of JSON is its considerable compactness in comparison with SOAP/XML, as well as the speed of analyzing requests on the Yandex Direct side.
Many programming languages have modules and libraries for working with JSON. The recommended modules and libraries for popular languages are listed below.
- Perl: JSON module.
- PHP: Built-in JSON support was added in version 5.2.0. For previous versions, you can use the Services_JSON library.
- Python: the json module.
The document contains samples for working with JSON in Perl, PHP, and Python.
JSON requests
Requests in JSON format are sent to the following address using the HTTP POST method:
Version 4
-
https://api.direct.yandex.ru/v4/json/
Live 4 version
-
https://api.direct.yandex.ru/live/v4/json/
The request always contains the method key with the name of the invoked method, and in most cases, also includes the param key (see the example below). Some methods do not have any input parameters, so the param key is not required for them.
Sample JSON request
This example demonstrates calling the GetClientInfo method. In the param key, an array is passed that consists of a single string, the username. The locale key sets the language for response messages. The token key is the access token issued by the Yandex OAuth server with the user's permission (for more information, see Authorization tokens).
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"
}
Language for responses
The request may contain the locale key, specifying the language for response messages. The selected language is used for returning campaign statuses, the status of banners, and error messages. The locale key may have the following values:
- ru — Russian
- uk — Ukrainian
- en — English
If the locale key is not specified, English is assumed.
Accessing finance methods
To access the finance methods CreateInvoice, TransferMoney, GetCreditLimits, and PayCampaigns, you must also specify the transaction number and the finance token in the operation_num and finance_token keys. To learn how they are generated, see Accessing finance methods.
Example of calling a finance method
Calling the GetCreditLimits finance method.
{
"method": "GetCreditLimits",
"finance_token": "07c2fbae9722634918bb00a70d2c467cf1bd07255012008ff249ba41b7a5cd6c",
"operation_num": 123,
"token": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f"
}
Error messages
When errors occur, request processing is terminated and an error message is returned in JSON format. An example of such a message is shown below.
{
"error_detail":"The POST method should be used for an HTTP request",
"error_str":"Invalid request method",
"error_code":512
}
The error_code parameter contains the error code, error_str contains a brief description of the error, and error_detail contains an additional explanation, if available. The brief description and additional explanation can be displayed in various languages; this is determined by the locale parameter that is specified when calling the method.