Get current XMLRiver account balance in rubles (₽).

Use this to check funds before bulk operations or to monitor spending.

Returns: Dict with balance_rub (float) or isError on failure.

Examples: get_balance() → {"balance_rub": 1234.56}

Get current XMLRiver tariff name.

Tariffs:

• 'Basic' — pay-as-you-go, no prepay, 25 ₽ per 1k requests

• 'Pro' — 5000 ₽/mo prepay, 20 ₽ per 1k

• 'Mega' — 15000 ₽/mo prepay, 15 ₽ per 1k

• 'Giga' — 50000 ₽/mo prepay, 12 ₽ per 1k

Returns: Dict with tariff (str) or isError.

Get expiration date for prepay tariff (Pro/Mega/Giga).

Returns 'never' or date for Basic tariff (no expiry).

Returns: Dict with expires_at (str) or isError.

Get cost per 1000 requests for a given engine, in rubles (₽).

Use this to estimate spend for a planned bulk operation. Cost depends on current tariff — see get_tariff for the tariff name.

Returns: Dict with engine, cost_per_1k_rub or isError.

Examples: get_cost(engine="google") → {"engine": "google", "cost_per_1k_rub": 25.0}

Parse Google search results page (SERP) for a given query and locale.

Use this for: SEO research (own/competitor ranking), keyword discovery, SERP feature analysis (featured snippets, knowledge graph, FAQ), competitive intel.

Do NOT use for: live page content fetching (use a dedicated scraper for that), Google Ads keyword planner data (use Yandex Wordstat via wordstat_query for RU).

Returns: Dict with: - query (echoed) - total_found — Google's reported result count - page — page number - results — list of organic results with position, url, title, snippet - addresults — featured_snippet, related_questions, related_searches, knowledge_graph (if present and requested via additional_blocks) - Or isError: True on XMLRiver error (15 = no results, 110 = rate limit, etc).

Examples: google_search(query="python tutorial", country=2008, language="ru") → {"results": [...10 organic results...], "total_found": 12300, "page": 1}

google_search(query="site:wikipedia.org python", country=2840, language="en")
→ results restricted to wikipedia.org domain

Check if a URL is indexed in Google or Yandex.

Internally uses url:<URL> operator with inindex=1 flag to xmlriver (forces fresh index check, not cache).

Use this for: SEO audits, indexation monitoring, "did Google find my new page?".

Returns: Dict with: - url — checked URL - search_engine - indexed — bool - details — full search results if indexed (with title, snippet, position)

Get Yandex Wordstat frequency for a keyword phrase.

Use this for: keyword research, demand validation, seasonality analysis, long-tail discovery. Russian/Yandex-speaking markets — this is Yandex's equivalent of Google Keyword Planner.

Do NOT use for: Google volume (Wordstat is Yandex-only — for Google use Google Keyword Planner or third-party tools).

Returns: Dict with: - query (echoed) - total_shows — total monthly impressions (главное число) - device_breakdown — {desktop, phone, tablet} if available - similar_queries — phrases users searched alongside (semantic core seed) - history — list of {date, count} if history_period != 'none' - Or isError: True on failure.

Examples: wordstat_query(query="купить iphone") → {"total_shows": 187234, "similar_queries": [...]}

wordstat_query(query="!купить +iphone +pro", region=213, history_period="monthly")
→ exact-form filtered, Moscow-only, 24-month dynamics

Parse Yandex search results page (SERP) for a given query and region.

Use this for: Russian SEO research (own/competitor ranking in Yandex), regional keyword analysis, SERP feature analysis (FAQ, knowledge graph), competitive intel for Russian-speaking markets.

Do NOT use for: keyword frequency data — use wordstat_query instead. Do NOT use for: structured JSON output — use yandex_search_api_v2 instead (official Yandex Search API proxy, cleaner JSON).

Returns: Dict with results (organic 10 items), total_found, page, addresults (related_questions, knowledge_graph, etc), or isError: True on failure.

Examples: yandex_search(query="купить iphone", region=213) → top 10 organic for Moscow

yandex_search(query="site:wildberries.ru игрушки", region=2)
→ site-restricted search for St. Petersburg

yandex_search(query="новости", within="77")
→ last-24-hours filtered

Query Yandex Search API v2 (official) via XMLRiver proxy.

Use this when you need: cleaner structured output, no SERP-feature parsing overhead, documented Yandex Search API semantics. Slightly more expensive than yandex_search (~24 ₽/1k vs 25 ₽/1k on Basic tariff).

Do NOT use for: SERP features (knowledge graph, FAQ, related questions) — those are not in the official API. Use yandex_search instead.

Returns: Parsed search results dict similar to yandex_search but without addresults.