# Google Lens Visual Search API — Image Matches (`khadinakbar/google-lens-visual-search`) Actor

Find Google visual-search matches for public image URLs. Returns Google-associated query context, organic source pages, image matches, refinement chips, and source provenance through a managed DataForSEO backend.

- **URL**: https://apify.com/khadinakbar/google-lens-visual-search.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** SEO tools, MCP servers, Automation
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $12.50 / 1,000 completed visual-search requests

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

## Google Lens Visual Search API — Reverse Image Matches

Turn a public image URL into a compact, structured visual-search record: Google-associated query context, source pages, image matches, refinement chips, and provider provenance. This focused API is designed for product researchers, brand-protection teams, marketplace analysts, and AI agents that need a bounded candidate set to review or enrich.

### Best fit and workflow guidance

Choose this Actor when a public source image is the starting point and the next decision depends on where visually related material appears on the web. It works well for identifying likely source pages, finding similar product listings, reviewing image reuse, and collecting a concise starting set for human or automated verification.

A marketplace analyst starts with a product image URL, then reviews the returned source pages and visual matches, compares prices or sellers in a downstream product workflow, and exports the evidence needed for a sourcing decision. For a text-reading workflow, pair this Actor with [Google Lens OCR](https://apify.com/zen-studio/google-lens-ocr) after visual discovery; that focused neighbor reads text from an image while this Actor produces visual-search matches.

This is a focused standalone workflow for image URL to Google visual-search candidates. It is designed as a focused standalone workflow when visual matching is the complete job.

### Quick start input

Provide one to ten publicly downloadable HTTP(S) image URLs. The source image stays with its host; the Actor sends its URL to the managed DataForSEO visual-search backend.

```json
{
  "imageUrls": [
    "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg"
  ],
  "maxResults": 10,
  "locationCode": 2840,
  "languageCode": "en"
}
```

`locationCode` is DataForSEO's numeric Google location ID. `2840` represents the United States. Every lookup uses DataForSEO's high-priority queue so the interactive API contract has one predictable provider route and one price.

### Output data

The dataset contains one row for every completed visual-search request. The compact record preserves both the original image URL and provider task ID so a downstream system can trace the lookup without receiving any credential.

| Field | Meaning |
| --- | --- |
| `imageUrl` | Public source image submitted for visual search. |
| `googleAssociatedQuery` | Keyword Google associated with the image, when present. |
| `organicMatches` | Source-page candidates with rank, title, URL, domain, and description. |
| `imageMatches` | Related image candidates with result URL, source domain, image URL, and thumbnail. |
| `refinementChips` | Google-provided visual-search refinements, when available. |
| `providerTaskId` | DataForSEO task ID for provenance and support. |
| `retrievedAt` | ISO collection time for this result row. |

```json
{
  "imageUrl": "https://example.com/catalog/blue-shoe.jpg",
  "googleAssociatedQuery": "blue running shoes",
  "checkUrl": "https://www.google.com/searchbyimage?...",
  "organicMatches": [
    {
      "rank": 1,
      "title": "Blue Running Shoe",
      "url": "https://shop.example/products/blue-shoe",
      "domain": "shop.example",
      "websiteName": "Example Shop",
      "description": "Product detail page for a blue running shoe.",
      "isImage": true,
      "isVideo": false
    }
  ],
  "imageMatches": [
    {
      "rank": 1,
      "title": "Blue shoe image",
      "url": "https://shop.example/products/blue-shoe",
      "sourceUrl": "https://shop.example/products/blue-shoe",
      "domain": "shop.example",
      "imageUrl": "https://shop.example/images/blue-shoe.jpg",
      "thumbnailUrl": "https://shop.example/images/blue-shoe-thumb.jpg"
    }
  ],
  "refinementChips": [
    { "title": "sneakers", "url": "https://www.google.com/search?...", "domain": "google.com" }
  ],
  "locationCode": 2840,
  "languageCode": "en",
  "providerTaskId": "00000000-0000-0000-0000-000000000000",
  "retrievedAt": "ISO-8601 collection timestamp",
  "provenance": {
    "source": "DataForSEO API v3",
    "endpoint": "serp/google/search_by_image/task_get/advanced",
    "providerCostUsd": 0.0012
  }
}
```

`OUTPUT` contains the terminal outcome and charge totals. `RUN_SUMMARY` adds non-secret task, provider, and request diagnostics. Both are available from the default key-value store after the task completes.

```json
{
  "outcome": "COMPLETE",
  "message": "Persisted 1 of 1 completed Google visual-search request(s).",
  "itemsPushed": 1,
  "itemsFailed": 0,
  "chargedEventCounts": { "visual-search-request": 1 },
  "warnings": []
}
```

### Pricing and cost control

This Actor uses Pay per event (PPE): `$0.0125` for each completed visual-search request persisted to the dataset, plus a `$0.00005` Actor-start event. Platform usage is charged separately under the Actor's Pay per event + usage configuration; consult the live Pricing tab for the current customer-facing configuration before scheduling production volume.

For example, ten completed image lookups produce ten `visual-search-request` events: `10 × $0.0125 = $0.125`, plus one `$0.00005` start event and applicable platform usage. The Actor respects an Apify maximum charge limit and records a `PARTIAL` terminal outcome when that limit stops more completed requests from being persisted.

### API example

```bash
curl -X POST 'https://api.apify.com/v2/acts/khadinakbar~google-lens-visual-search/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"],
    "maxResults": 10,
    "locationCode": 2840,
    "languageCode": "en"
  }'
```

Retrieve the resulting rows from the task's default dataset, then read `OUTPUT` when a concise terminal outcome is more useful than the full record set.

### AI agent prompt card

> Given this public image URL, execute Google Lens Visual Search API with ten matches in the relevant location. Read the dataset after completion, retain the source URL and collection time, cite `providerTaskId` as provenance, and report the terminal `outcome`, total cost events, and any pagination scope before using matches for a decision.

The Actor is suitable for an AI agent or MCP-style workflow because the input is small and the output makes freshness, provenance, scope, and billing explicit. An agent can pass the selected source-page URLs to its own enrichment, monitoring, or product-comparison workflow after reviewing the returned dataset.

### Best results

Start with a stable, publicly accessible direct image URL. Product hero images, high-resolution catalog images, and a single clear subject usually provide the most useful visual-search context. Select the location and language that match the market being investigated, and confirm the source page and rights before acting on a candidate match.

The managed backend accepts public HTTP(S) source images and returns a bounded match set of up to 20 organic and image entries per image. Use the returned `checkUrl`, source URLs, and collection time to validate current availability in a workflow where the decision has material impact.

### Scope and complementary workflows

Use this Actor for visual discovery from a publicly downloadable image URL. File uploads, OCR text extraction, rights verification, page crawling, and duplicate-proof review belong in focused complementary workflows. Google can return a legitimate zero-match result; the Actor still persists the completed lookup with empty match arrays, `provenance.providerStatus: "no_search_results"`, and request-level `valid_empty` status in `RUN_SUMMARY`. Add an OCR, web-crawl, or rights-review workflow when those jobs are required.

### Builder's note

I designed this Actor around one durable job: turning a public image URL into a compact record that another workflow can evaluate. My goal was to keep credentials and provider mechanics out of the user's input while retaining provider task IDs, source URLs, collection time, and event-count visibility for practical review.

### Responsible use

Use images and resulting source pages only when you are authorized to access and collect them, and follow applicable laws, copyright obligations, and site terms. Visual-search candidates are leads for review; confirm ownership, licensing, and source-page facts in the relevant downstream workflow.

# Actor input Schema

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

One to ten publicly reachable HTTP(S) image URLs, for example \["https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon\_Musk\_Royal\_Society.jpg"]. Each URL is submitted to the managed visual-search backend once. Do not use webpage URLs, private network URLs, data URIs, or local file paths; the source image must be publicly downloadable.

## `maxResults` (type: `integer`):

Maximum normalized organic and image-match entries returned for each source image, from 1 to 20. The backend may inspect a wider SERP to find matches, but this setting caps the dataset payload. Defaults to 10; use 20 only when downstream code needs a broader candidate set.

## `locationCode` (type: `integer`):

DataForSEO Google location code that localizes the visual-search SERP, for example 2840 for the United States. Defaults to 2840. This is a DataForSEO numeric location ID, not an ISO country code or a postal code.

## `languageCode` (type: `string`):

Two-letter Google/DataForSEO language code for result text, for example en, de, or fr. Defaults to en. This controls result language; use locationCode separately for geography.

## Actor input object example

```json
{
  "imageUrls": [
    "https://upload.wikimedia.org/wikipedia/commons/e/ed/Elon_Musk_Royal_Society.jpg"
  ],
  "maxResults": 10,
  "locationCode": 2840,
  "languageCode": "en"
}
```

# Actor output Schema

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

One normalized visual-search result per successfully completed image request.

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

Compact terminal outcome, completed requests, event charges, and warnings.

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

Detailed provider attempts, task IDs, cost, and terminal outcome.

# 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"
    ],
    "maxResults": 10,
    "locationCode": 2840,
    "languageCode": "en"
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/google-lens-visual-search").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"],
    "maxResults": 10,
    "locationCode": 2840,
    "languageCode": "en",
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/google-lens-visual-search").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"
  ],
  "maxResults": 10,
  "locationCode": 2840,
  "languageCode": "en"
}' |
apify call khadinakbar/google-lens-visual-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/google-lens-visual-search"
        }
    }
}

```

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/S5sZchzMPy6dfdZAU/builds/1vlgbKfFHAQKYLDaM/openapi.json