Yandex Direct

Yandex Direct

This connector reads Yandex Direct API v5 (https://api.direct.yandex.com/json/v501) with an OAuth token: the advertiser account, campaigns, ad groups, ads, keywords and bids, sitelinks, callouts, negative keyword sets, retargeting lists, agency clients, dictionaries, change tracking and statistics reports. Every tool is read-only; nothing here creates, changes, pauses or pays for anything.

Setup (about 10 minutes, once)

1. Register an app at https://oauth.yandex.ru (platform: web services, permission Yandex Direct API, direct:api). Note its ClientID.
2. In the Yandex Direct web interface open Tools, API and submit an API access request for that ClientID (it needs at least one campaign in the account; approval takes from an hour to a few business days). Accept the API user agreement there.
3. Get a token: sign in with the Direct account and open https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>; copy the access_token (it starts with y0_) into YANDEX_DIRECT_TOKEN. It is valid for about a year and is extended while it is used. It is sent as Authorization: Bearer ... and only to api.direct.yandex.com.
4. Agencies only: set YANDEX_DIRECT_CLIENT_LOGIN to the advertiser's login to read that advertiser (sent as Client-Login); yandex_direct_list_agency_clients lists the logins. Leave it empty for your own account.

Where to start: yandex_direct_get_client (account, currency), yandex_direct_list_campaigns, then yandex_direct_list_ad_groups, yandex_direct_list_ads and yandex_direct_list_keywords with up to 10 campaign_ids. Performance numbers come from yandex_direct_get_report.

Money: object amounts (bids, budgets, Funds) are integers in micros: 2500000 = 2.50 in the account currency (yandex_direct_get_client gives it). Reports return decimals instead.

Reports (yandex_direct_get_report): the answer is tab-separated text, the first line the column names. report_name must be unique for each set of parameters. Small reports come back at once; larger ones are built offline: the answer is then empty with a retryin header (seconds). Call again with exactly the same parameters and name after that time. At most 5 offline reports can be queued; search query reports are offline only and cover the last 180 days. With CUSTOM_DATE pass date_from and date_to; with any other period leave them out.

Paging: lists return up to limit objects (default 500, at most 10,000). If the answer has LimitedBy, pass that number as offset for the next page.

Points (units): every call spends API points from the advertiser's daily allowance (the Units limit); a failed call costs 20. Prefer one call with several ids over many single calls and ask only for the fields you need.

Errors arrive as {"error": {"error_code", "error_string", "error_detail"}} and are passed on as errors: 53 the token is invalid or expired (get a new one, step 3), 54 or 3000/3001 no API access or no rights (the access request of step 2, or a Client-Login the token may not read), 513 the login is not connected to Direct, 152 not enough points today, 506 too many parallel requests, 8000 and 4000 to 4006 a wrong parameter, 8800 not found, 9300 too many ids in one call.

Out of scope: creating or editing campaigns, ads, keywords and bids, moderation, budgets and payments, the Sandbox and Wordstat.