{
  "markdown": "**English** | [Русский](README.ru.md)\n\n# 🔎 Yandex API: Structured Yandex Search Results in Clean JSON\n\n> The most efficient, reliable, and developer-friendly way to use the Yandex API.\n\n**Actor page:** [apify.com/johnvc/Scrape-Yandex](https://apify.com/johnvc/Scrape-Yandex?fpr=9n7kx3)\n**Input schema:** [apify.com/johnvc/Scrape-Yandex/input-schema](https://apify.com/johnvc/Scrape-Yandex/input-schema?fpr=9n7kx3)\n\nThe Yandex API runs a Yandex search for any query and returns clean, structured JSON. Choose the result types you want a la carte (organic listings, paid ads, knowledge graph entity cards, inline image panels, inline video panels); each selected type comes back as its own item tagged with `item_type`, plus per-page metadata. It supports 6 Yandex domains, 19 languages, and region targeting across 123,000+ locations, with sort/recency filters and fast parallel pagination.\n\n## Video Walkthrough\n\n[![Watch the walkthrough](https://img.youtube.com/vi/jREWahDGhJM/maxresdefault.jpg)](https://www.youtube.com/watch?v=jREWahDGhJM)\n\n## Quick Start\n\n### Prerequisites\n- Python 3.11 or higher\n- An Apify account and API key ([get a free key here](https://apify.com?fpr=9n7kx3))\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/johnisanerd/Apify-Yandex-Search-Scraper.git\n   cd Apify-Yandex-Search-Scraper\n   ```\n\n2. **Install dependencies with UV**\n   ```bash\n   # Install UV if you do not have it:\n   curl -LsSf https://astral.sh/uv/install.sh | sh\n\n   # Install project dependencies:\n   uv sync\n   ```\n\n3. **Configure your API key**\n   ```bash\n   cp .env.example .env\n   # Edit .env and add your Apify API key\n   # Get your free API key at: https://apify.com?fpr=9n7kx3\n   ```\n\n4. **Run the example**\n   ```bash\n   uv run python yandex-scraper.py\n   ```\n\n### Alternative: set the API key directly\n```bash\nexport APIFY_API_TOKEN=\"your_api_key_here\"\nuv run python yandex-scraper.py\n```\n\n## Why Use This Yandex API?\n\n**Full results-page coverage.** One call returns the whole Yandex results page as structured data: organic listings, paid ads, knowledge graph entity cards, inline image panels, and inline video panels. You get the entire page, not just the organic links.\n\n**Built for Russian-speaking and CIS markets.** Target 6 Yandex domains (yandex.com, yandex.ru, yandex.by, yandex.kz, yandex.uz, yandex.com.tr), 19 languages, and any of 123,000+ region IDs. That makes it practical for SEO, competitive intelligence, and brand monitoring across Russia, Eastern Europe, Central Asia, and beyond.\n\n**Predictable, pay-per-use pricing.** Billing is per run plus per page processed, with no monthly rental. You pay for the searches you actually make, and you control cost directly with the page limit.\n\n**Clean, consistent JSON.** Every page is a structured dataset item with the same shape, so you parse results once and reuse the code across queries, domains, and languages.\n\n**Easy to automate.** Call it from Python in a few lines, or load it as an MCP tool so assistants like Claude and Cursor can run Yandex searches for you on demand.\n\n## Features\n\n### Core Capabilities\n- **Keyword search** across Yandex with full results-page extraction\n- **A la carte result types**: toggle organic results, ads, knowledge graph, inline images, and inline videos independently; each selected type is returned as its own item tagged with `item_type`\n- **Domain localization** across 6 Yandex domains\n- **Language targeting** with 19 supported languages\n- **Region targeting** with 123,000+ location IDs (the `lr` parameter)\n- **Sort and recency filters**: `sort_mode` (relevance or date) and `period` (all, day, last_two_weeks, month)\n- **Safe search and typo correction** controls, plus fast parallel multi-page pagination\n\n### Data Quality\n- **Structured organic results** with title, link, snippet, position, displayed link, date, and sitelinks\n- **Rich result blocks**: ads, knowledge graph, inline images, inline videos, each with a `result_count`\n- **Per-page metadata** with domain, language, location, and pagination details\n- **Consistent JSON** shape across every query\n- **Per-page billing** so larger searches stay transparent\n\n## Usage Examples\n\n### Basic Example\nA single-page search for one keyword. This is the cheapest way to try the API.\n```json\n{\n  \"text\": \"machine learning\",\n  \"yandex_domain\": \"yandex.com\",\n  \"max_pages\": 1\n}\n```\n\n### Advanced Example\nA Russian-domain search with Russian language, a region ID, more results per page, and two pages.\n```json\n{\n  \"text\": \"машинное обучение\",\n  \"yandex_domain\": \"yandex.ru\",\n  \"lang\": \"ru\",\n  \"lr\": 225,\n  \"groups_on_page\": 20,\n  \"family_mode\": 1,\n  \"max_pages\": 2\n}\n```\n\n### A la carte: collect ads and the knowledge graph\nEnable just the result types you want. Here organic is off and only ads plus the knowledge graph are returned, each as its own item.\n```json\n{\n  \"text\": \"best running shoes\",\n  \"include_organic_results\": false,\n  \"include_ads\": true,\n  \"include_knowledge_graph\": true,\n  \"max_pages\": 1\n}\n```\n\n### Fresh results: sort by date, last two weeks\nUse `sort_mode` and `period` to focus on recent content. They apply to every selected result type.\n```json\n{\n  \"text\": \"ai news\",\n  \"yandex_domain\": \"yandex.ru\",\n  \"lang\": \"ru\",\n  \"sort_mode\": \"date\",\n  \"period\": \"last_two_weeks\",\n  \"max_pages\": 1\n}\n```\n\n## Input Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `text` | `string` | Yes | - | The search query. Supports Yandex operators such as `site:wikipedia.org python`. |\n| `include_organic_results` | `boolean` | No | `true` | Return organic results (`item_type` `organic`). |\n| `include_ads` | `boolean` | No | `false` | Return paid ads when present (`item_type` `ads`). |\n| `include_knowledge_graph` | `boolean` | No | `false` | Return the knowledge graph card when present (`item_type` `knowledge_graph`). |\n| `include_inline_images` | `boolean` | No | `false` | Return the inline image strip (`item_type` `inline_images`). |\n| `include_inline_videos` | `boolean` | No | `false` | Return the inline video carousel (`item_type` `inline_videos`). |\n| `yandex_domain` | `string` | No | `yandex.com` | Yandex domain, e.g. `yandex.ru`, `yandex.com.tr`, `yandex.kz` (6 supported). |\n| `lang` | `string` | No | `en` | Language code, e.g. `ru`, `en`, `tr`, `de` (19 supported); `null` for unspecified. |\n| `lr` | `integer` | No | (domain default) | Region ID, e.g. `225` = Russia, `84` = United States, `149` = Belarus. 123,000+ IDs; see the Actor page for the full table. |\n| `max_pages` | `integer` | No | `2` | Maximum pages to fetch (`0` = no limit). Applies to every selected result type. |\n| `sort_mode` | `string` | No | `relevance` | Result ordering: `relevance` or `date` (newest first). |\n| `period` | `string` | No | `all` | Recency window: `all`, `day`, `last_two_weeks`, `month`. |\n| `groups_on_page` | `integer` | No | `10` | Results per page (1 to 20). |\n| `family_mode` | `integer` | No | `1` | Safe search: `0` = off, `1` = moderate, `2` = strict. |\n| `fix_typo` | `boolean` | No | `true` | Auto-correct spelling errors in the query. |\n| `output_file` | `string` | No | (none) | Optional filename to save results; auto-generated if omitted. |\n\n## Output Format\n\nEach selected result type present on a page is returned as its own dataset item, tagged with `item_type` (`organic`, `ads`, `knowledge_graph`, `inline_images`, or `inline_videos`) and a `result_count`. A representative `organic` item for the query `Apple` is shown below; arrays and some fields are trimmed here for readability.\n\n```json\n{\n  \"item_type\": \"organic\",\n  \"result_count\": 10,\n  \"text\": \"Apple\",\n  \"yandex_domain\": \"yandex.com\",\n  \"lang\": \"en\",\n  \"lr\": \"84\",\n  \"page_number\": 1,\n  \"search_domain\": \"yandex.com\",\n  \"search_domain_description\": \"United States\",\n  \"search_language\": \"en\",\n  \"search_language_description\": \"English\",\n  \"search_location\": \"84\",\n  \"total_results_found\": 10,\n  \"pages_processed\": 1,\n  \"total_pages\": 1,\n  \"max_pages_set\": 1,\n  \"results_per_page\": 10,\n  \"pagination_limit_reached\": true,\n  \"pagination_stopped_by_limit\": true,\n  \"organic_results\": [\n    {\n      \"position\": 1,\n      \"title\": \"Apple\",\n      \"link\": \"https://www.apple.com/\",\n      \"displayed_link\": \"apple.com\",\n      \"snippet\": \"Apple Payments Services LLC, a subsidiary of Apple Inc., is a service provider of Goldman Sachs Bank USA for Apple Card and Savings accounts.\"\n    },\n    {\n      \"position\": 3,\n      \"title\": \"Apple Inc. - Wikipedia\",\n      \"link\": \"https://en.m.wikipedia.org/wiki/Apple_Inc.\",\n      \"displayed_link\": \"en.m.wikipedia.org\",\n      \"snippet\": \"Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley.\"\n    }\n  ],\n  \"ads_results\": [],\n  \"knowledge_graph\": [\n    {\n      \"title\": \"Apple Inc.\",\n      \"description\": \"American multinational technology company headquartered in Cupertino, California.\",\n      \"source\": { \"name\": \"en.wikipedia.org\" }\n    }\n  ],\n  \"inline_images\": [],\n  \"inline_videos\": []\n}\n```\n\n---\n\n## Use as an MCP tool\n\nYou can load the Yandex API as an MCP tool so assistants call it for you. The MCP server URL preloads just this one Actor:\n\n```\nhttps://mcp.apify.com/?tools=actors,docs,johnvc/Scrape-Yandex\n```\n\nAuthenticate with OAuth in the browser when offered, or with your Apify API token (the same `APIFY_API_TOKEN` used by the Python example). Get a token at https://console.apify.com/settings/integrations and a free Apify account at https://apify.com?fpr=9n7kx3 .\n\n## Install in Claude Cowork Desktop\n\n![Install in Claude Cowork Desktop](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_claude_desktop.png)\n\nCowork is the desktop app's automation mode. To give it the Yandex API as a tool, add the Apify MCP server as a connector.\n\n1. Open the Claude desktop app and go to **Settings → Connectors** (or **Settings → Developer → Edit Config** to edit `claude_desktop_config.json` directly).\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n2. Add the Apify MCP server, preloaded with only this Actor:\n\n```json\n{\n  \"mcpServers\": {\n    \"apify\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://mcp.apify.com/?tools=actors,docs,johnvc/Scrape-Yandex\"\n      ]\n    }\n  }\n}\n```\n\n3. Restart the app. When Cowork first calls the tool, complete the OAuth prompt in your browser, or add your Apify API token in the connector settings to skip OAuth.\n4. In a Cowork chat, confirm the tool is available and ask it to run the Yandex API.\n\nDownload the desktop app and start a free trial: https://claude.ai/referral/uIlpa7nPLg\nMore help: https://docs.apify.com/platform/integrations/claude-desktop\n\n## Install in Claude Code\n\n![Install in Claude Code](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_claude_code.png)\n\nClaude Code is the command-line tool. Add the Actor's MCP server with one command:\n\n```bash\nclaude mcp add --transport http apify \\\n  \"https://mcp.apify.com/?tools=actors,docs,johnvc/Scrape-Yandex\"\n```\n\nTo use a token instead of browser OAuth:\n\n```bash\nclaude mcp add --transport http apify \\\n  \"https://mcp.apify.com/?tools=actors,docs,johnvc/Scrape-Yandex\" \\\n  --header \"Authorization: Bearer YOUR_APIFY_TOKEN\"\n```\n\nThen verify with `claude mcp list`, or run `/mcp` inside a session. Ask Claude Code to call the Yandex API.\n\nTry Claude Code free: https://claude.ai/referral/uIlpa7nPLg\nClaude Code MCP docs: https://code.claude.com/docs/en/mcp\n\n## Install in Claude (website)\n\n![Install in Claude (website)](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_claude_ai.png)\n\nOn claude.ai you add Apify as a connector, then enable just this Actor's tool.\n\n1. Go to **Settings → Connectors → Browse connectors** and search for **Apify MCP server**. Install it (enable or update if prompted).\n2. When connecting, authenticate with your Apify API token, and enable the tool `johnvc/Scrape-Yandex`.\n3. In any chat, open **+ → Connectors** and turn on **Apify**.\n4. Alternatively, choose **Add custom connector** and paste the full MCP URL `https://mcp.apify.com/?tools=actors,docs,johnvc/Scrape-Yandex`, using OAuth when prompted.\n5. Ask Claude to run the Yandex API.\n\nOpen Claude on the web: https://claude.ai/referral/uIlpa7nPLg\n\n## Install in Cursor\n\n![Install in Cursor](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_cursor.png)\n\nCursor reads MCP servers from a project file at `.cursor/mcp.json`.\n\n1. In your project, create `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"apify\": {\n      \"url\": \"https://mcp.apify.com/?tools=actors,docs,johnvc/Scrape-Yandex\"\n    }\n  }\n}\n```\n\n2. If you prefer token auth over browser OAuth, add a header:\n\n```json\n{\n  \"mcpServers\": {\n    \"apify\": {\n      \"url\": \"https://mcp.apify.com/?tools=actors,docs,johnvc/Scrape-Yandex\",\n      \"headers\": { \"Authorization\": \"Bearer YOUR_APIFY_TOKEN\" }\n    }\n  }\n}\n```\n\n3. Open **Cursor → Settings → MCP** and confirm the **apify** server is connected (green dot).\n4. In Composer or Chat, ask Cursor to call the Yandex API.\n\nNew to Cursor? Get it here: https://cursor.com/referral?code=XQP4VBLI3NNX\n\n## Install in ChatGPT\n\n![Install in ChatGPT](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_ChatGPT.png)\n\nChatGPT connects to the Apify MCP server through Developer mode (available on ChatGPT Pro, Plus, Business, Enterprise, and Education plans).\n\n1. Click your profile icon, then go to **Settings > Apps**. If you do not see a **Create app** button, open **Advanced settings** and enable **Developer mode**.\n2. Click **Create app** and fill out the form:\n   - **Name:** Apify\n   - **MCP Server URL:** `https://mcp.apify.com/?tools=actors,docs,johnvc/Scrape-Yandex`\n   - **Authentication:** OAuth\n3. Click **Create** and authorize the connection with Apify.\n4. To use the app in a conversation, click **+** in the chat, choose **Developer mode**, and select **Apify**.\n\nMore help: https://docs.apify.com/platform/integrations/mcp\n\n---\n\n[**Made with care**](https://apify.com/johnvc?fpr=9n7kx3)\n\n*Use the Yandex API to power your search and SEO workflows with reliable, structured results.*\n\nLast Updated: 2026.09.07\n",
  "bytes": 14485,
  "sha": "2ad682c3e36c223a2299bb581e084b3ad20ac325bd66f8306a7750359d531847",
  "repo_slug": "johnisanerd/apify-yandex-search-scraper",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_johnisanerd_yandex_search_5c3b50ce/readme"
}