# Yandex Reverse Image Search API — Image Matches (`khadinakbar/yandex-reverse-image-search-api`) Actor

Reverse-search public image URLs on Yandex Images. Returns source pages, visually similar images, image tags, and alternate sizes as a bounded record per submitted image.

- **URL**: https://apify.com/khadinakbar/yandex-reverse-image-search-api.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Developer tools, SEO tools, Automation
- **Stats:** 2 total users, 1 monthly users, 25.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 completed image searches

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Yandex Reverse Image Search API — Image Matches

Turn one or more public image URLs into structured Yandex reverse-image-search evidence. Each completed lookup produces one compact dataset record containing source-page candidates, visually similar images, Yandex search tags, optional alternate sizes, collection time, and a direct result URL for review.

This Actor is for brand-protection reviews, product and marketplace research, image-provenance research, and content-reuse investigation. Its focused contract is public HTTP(S) image URLs to reverse-image evidence; image uploads, OCR, translation, and identity verification belong in dedicated workflows.

### Best fit and workflow guidance

Use this Actor when a source image is the starting point and you need a bounded set of web pages or visual candidates to review. A product researcher can submit a catalog image, inspect `sites` and `similarImages`, then send the returned page URLs to a product or seller-enrichment workflow. A rights holder can review where a public image appears, then independently verify context, ownership, licensing, and any action they take.

Choose a text-based image scraper when you already have keywords. Choose an OCR-specific tool when the job is to read visible text. This Actor is deliberately narrow: public image URL in, Yandex reverse-image evidence out.

### Quick start

Submit one to ten direct, public image URLs. The default result includes source-page candidates, visually similar images, and Yandex tags; alternate sizes are optional.

```json
{
  "imageUrls": [
    "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg"
  ],
  "maxResultsPerImage": 20,
  "includeSites": true,
  "includeSimilarImages": true,
  "includeTags": true,
  "includeImageSizes": false,
  "yandexDomain": "yandex.com"
}
```

Use a direct image file URL rather than a webpage URL. Private-network hosts, local files, IP literals, `data:` URLs, and login-protected images are rejected before an upstream request. `maxResultsPerImage` limits each enabled result group independently, from 1 to 50.

### Output data

The default dataset has one row per completed source-image lookup. A zero-match lookup is still a meaningful completed record: its result arrays are empty and the terminal outcome is `VALID_EMPTY`.

| Field | Meaning |
| --- | --- |
| `imageUrl` | The public source image submitted for lookup. |
| `searchUrl` | Direct Yandex result URL for manual review. |
| `sites` | Page candidates where Yandex surfaced the image or a close visual match. |
| `similarImages` | Visually similar image candidates with a Yandex result URL. |
| `imageTags` | Yandex-provided search suggestions that serve as follow-up research hints. |
| `imageSizes` | Optional alternate image URLs and dimensions exposed in the result. |
| `matchedEntity` | Optional Yandex result-card context when exposed. |
| `matchCount` | Total retained candidates across the enabled groups. |
| `retrievedAt` | ISO 8601 collection time. |
| `provenance` | Public result-surface and parser version used for the record. |

```json
{
  "imageUrl": "https://example.com/catalog/blue-shoe.jpg",
  "searchUrl": "https://yandex.com/images/search?rpt=imageview&url=https%3A%2F%2Fexample.com%2Fcatalog%2Fblue-shoe.jpg",
  "yandexDomain": "yandex.com",
  "matchedEntity": null,
  "sites": [
    {
      "rank": 1,
      "title": "Blue running shoe",
      "url": "https://shop.example/products/blue-shoe",
      "domain": "shop.example",
      "thumbnailUrl": "https://images.example/blue-shoe-thumb.jpg",
      "matchedImageUrl": "https://images.example/blue-shoe.jpg"
    }
  ],
  "similarImages": [
    {
      "rank": 1,
      "imageUrl": "https://images.example/similar-shoe.jpg",
      "title": "Blue running shoe",
      "resultUrl": "https://yandex.com/images/search?..."
    }
  ],
  "imageTags": [{ "label": "blue sneakers", "searchUrl": "https://yandex.com/images/search?text=blue+sneakers" }],
  "imageSizes": [],
  "matchCount": 3,
  "retrievedAt": "ISO-8601 collection timestamp",
  "provenance": { "source": "Yandex Images public result page", "parserVersion": "0.1", "resultSurface": "rpt=imageview" }
}
```

`OUTPUT` exposes the stable terminal outcome and billed-event count. `RUN_SUMMARY` adds safe per-image status, retry, result-coverage, and spend-limit diagnostics. Both records live in the default key-value store.

### Pricing and cost control

The configured price is `$0.02` for each completed and persisted image search, plus `$0.00005` per Actor start. Pay per event (PPE) plus platform usage keeps the search event and compute/proxy usage visible separately; the live Pricing tab is the current source of truth before scheduling production volume.

Set an Apify maximum charge limit to cap a batch. When that limit ends later source-image processing, the Actor retains completed rows and records a `PARTIAL` outcome with a warning. Input guidance, challenge detection, and result-surface validation keep the dataset focused on completed-search records.

### API example

```bash
curl -X POST 'https://api.apify.com/v2/acts/khadinakbar~yandex-reverse-image-search-api/runs?token=YOUR_APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "imageUrls": ["https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg"],
    "maxResultsPerImage": 20,
    "includeSites": true,
    "includeSimilarImages": true,
    "includeTags": true,
    "includeImageSizes": false,
    "yandexDomain": "yandex.com"
  }'
```

After completion, retrieve the default dataset for the structured records and read `OUTPUT` for the concise terminal result. The exact Actor path is available after the private deployment step.

### AI agent prompt card

> Reverse-search this public image URL with Yandex. Keep at most 20 candidates per enabled group, read the dataset after completion, preserve `searchUrl` and `retrievedAt` as provenance, treat Yandex tags as research hints, and report the terminal outcome, completed-search event count, and warnings before using a candidate in a decision.

### Best results

Use a stable, publicly downloadable image that is at least moderately clear and has a direct URL. Product images, artwork, editorial photos, and catalogue images work best when the subject is visible and not heavily compressed. Start with the default `yandex.com` surface; test another supplied regional domain only when it reflects the market you are researching.

Returned pages and visual candidates are starting points for rights, source, availability, and context review. Confirm current page content and rights independently when a decision is material.

### Responsible use

Use images and resulting pages only when you are authorized to access and collect them, and comply with applicable laws, copyright obligations, and site terms. Keep human review in any high-impact decision involving people. Yandex is a trademark of its respective owner; this independent Actor has no affiliation with Yandex.

### Builder's note

I built this Actor around Yandex Images' public `rpt=imageview` result surface, using direct-image inputs and residential proxy sessions. I added private/local URL rejection before any request, bounded retries, explicit challenge/layout-drift detection, and SDK-coupled dataset writes so a completed-search event always has a complete persisted record. `OUTPUT` and `RUN_SUMMARY` make the terminal evidence reviewable without exposing session data.

### Related workflows

- [Google Images Scraper](https://apify.com/khadinakbar/google-images-scraper) for keyword-first image discovery.
- [Yandex Maps Scraper](https://apify.com/khadinakbar/yandex-maps-scraper) for location-first Yandex business research.
- [Alibaba Listings Scraper](https://apify.com/khadinakbar/alibaba-listings-scraper) when a visual candidate needs marketplace listing details.

### Your feedback

If a public image URL produces an unexpected result, share the URL only when you have permission to do so, the selected regional domain, and the terminal `RUN_SUMMARY` outcome. Keep API tokens, cookies, and private image URLs out of support requests.

# Actor input Schema

## `imageUrls` (type: `array`):

One to ten publicly downloadable HTTP(S) image URLs, for example \["https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon\_Musk\_Royal\_Society.jpg"]. Each URL is reverse-searched once. Do not use a webpage URL, local network address, data URI, or file path; Yandex must be able to fetch the source image directly.

## `maxResultsPerImage` (type: `integer`):

Maximum entries retained in each result group for one source image, from 1 to 50. This bounds source-page, similar-image, tag, and size arrays independently. Defaults to 20; it does not change the number of source images searched.

## `includeSites` (type: `boolean`):

Return Yandex source-page candidates where the submitted image or a close visual match appears. Defaults to true. Turn this off only when you need visual candidates without page-level context.

## `includeSimilarImages` (type: `boolean`):

Return Yandex visually similar image candidates for each submitted image. Defaults to true. These are image-discovery candidates, not a claim that each item is an exact duplicate.

## `includeTags` (type: `boolean`):

Return Yandex descriptive tag suggestions when the result page exposes them. Defaults to true. Tags are Yandex-provided search hints, not verified labels or identity claims.

## `includeImageSizes` (type: `boolean`):

Return alternate image URLs and dimensions exposed in Yandex's other-sizes section. Defaults to false because this section may add less useful variants. It does not download any returned image.

## `yandexDomain` (type: `string`):

Yandex Images regional domain used for the lookup. Defaults to yandex.com. Choose a listed domain only when regional presentation matters; this is not a country or language filter.

## Actor input object example

```json
{
  "imageUrls": [
    "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg"
  ],
  "maxResultsPerImage": 20,
  "includeSites": true,
  "includeSimilarImages": true,
  "includeTags": true,
  "includeImageSizes": false,
  "yandexDomain": "yandex.com"
}
```

# Actor output Schema

## `results` (type: `string`):

One structured Yandex result record per completed source-image lookup.

## `output` (type: `string`):

Compact terminal outcome, item totals, charged-event counts, and warnings.

## `runSummary` (type: `string`):

Detailed non-secret request diagnostics and result coverage.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "imageUrls": [
        "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg"
    ],
    "maxResultsPerImage": 20,
    "includeSites": true,
    "includeSimilarImages": true,
    "includeTags": true,
    "includeImageSizes": false,
    "yandexDomain": "yandex.com"
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/yandex-reverse-image-search-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "imageUrls": ["https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg"],
    "maxResultsPerImage": 20,
    "includeSites": True,
    "includeSimilarImages": True,
    "includeTags": True,
    "includeImageSizes": False,
    "yandexDomain": "yandex.com",
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/yandex-reverse-image-search-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "imageUrls": [
    "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg"
  ],
  "maxResultsPerImage": 20,
  "includeSites": true,
  "includeSimilarImages": true,
  "includeTags": true,
  "includeImageSizes": false,
  "yandexDomain": "yandex.com"
}' |
apify call khadinakbar/yandex-reverse-image-search-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/yandex-reverse-image-search-api"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/SgQ4Rx5GGXNekPmaU/builds/33rQB5nfW9OEwPO50/openapi.json