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 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.

{
  "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.

{
  "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.

{
  "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

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.