yseo

Русская версия

A read-only command line client for the Yandex Webmaster and Yandex Metrica APIs (plus Yandex Direct). Python standard library only — no dependencies, no virtualenv, one file.

Yandex's web consoles are fine for looking at one site, but bad at answering "what changed across my sites this week" and impossible to script. This wraps the official APIs in a CLI that prints plain tables for reading and raw JSON for piping. Everything is a GET (Direct's reporting endpoint is a POST, but nothing here creates or modifies anything), so the worst it can do is show you numbers.

How it works

Single file, yseo.py, symlinked as yseo on PATH. urllib.request against three API bases — api.webmaster.yandex.net/v4, api-metrika.yandex.net (management + stat), and api.direct.yandex.com/json/v5 — with OAuth bearer headers, JSON in, tables out.

Two details that make it usable day to day:

• Sites are resolved by substring. Webmaster host IDs are opaque strings and Metrica counters are numeric IDs; you pass example and it resolves to https://www.example.ru. Metrica also accepts a raw counter ID.
• Failures are diagnosed, not just raised. Webmaster can silently drop the connection on an invalid token instead of returning 401, so requests are retried once and a dropped connection is reported as "probably a bad token" rather than a network error. 401/403 responses append the re-auth command.

Every command takes --json to emit the raw API response instead of a table, which is what makes it useful as a building block for reports.

Stack

Python 3, stdlib only (urllib, json, argparse, http.client).

Usage

yseo webmaster sites                          # sites in Webmaster
yseo webmaster queries example.ru             # top queries: impressions / clicks / position
yseo webmaster queries example --days 28 --order shows --limit 50
yseo webmaster index example.ru               # site quality index, pages in search, history
yseo webmaster sitemaps example.ru            # sitemap files, URL counts, errors

yseo metrika counters                         # Metrica counters
yseo metrika traffic example.ru               # visits and sources, last 30 days
yseo metrika traffic 12345678 --days 7        # or by counter ID
yseo metrika pages example.ru --limit 40      # top pages by views

yseo direct campaigns                         # Direct campaigns (own account)
yseo direct costs --days 30                   # impressions / clicks / spend incl. VAT

Credentials

You need one Yandex OAuth token for the account that owns the Webmaster and Metrica properties.

1. Register an app at https://oauth.yandex.ru/client/new, platform "Web services", redirect URI https://oauth.yandex.ru/verification_code.
2. Request these scopes:
   • webmaster:verify — this is the one that actually returns API data. webmaster:hostinfo only gets you the site list, and webmaster:api is not offered in the scope picker.
   • metrika:read
   • direct:api — only if you want the direct subcommands.
3. Open https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>, approve, and copy the token from the page.
4. yseo token <TOKEN> — it verifies access against both APIs immediately.

The token is stored in ~/.config/yseo/config.json with mode 600, or can be supplied via the YSEO_TOKEN environment variable. No credentials are stored in this repo.