# Google Lens API

> Source: https://scrape.do/documentation/google-scraper-api/lens/

Search Google Lens by image URL and return visual matches, exact-image pages, and related searches as structured JSON

The Google Lens API searches with a public image URL and returns structured JSON. Use it to find visually similar images, discover pages that contain the exact image, identify products and prices, or collect related search suggestions without rendering Google Lens yourself.

> [!NOTE]
> **Credit Usage:** Each successful request costs **10 credits**, regardless of the selected result type. A search that finds no matches, or whose image Google cannot load, still succeeds and costs 10 credits. Failed requests that return `502` are not charged. To run many searches, send requests in parallel; your plan's concurrency limit applies.

## Key Features

- **Visual matches**: find pages with visually similar images and receive page, source, thumbnail, and full-size image details.
- **Exact-image matches**: use `type=exact` to find pages that contain the same image.
- **Product data**: receive prices, normalized price values, currencies, ratings, review counts, and stock status when Google shows them.
- **Combined image and text search**: add `q` to refine visual matches by color, model, product detail, or another keyword.
- **Related searches**: the default `type=all` response includes Google's suggested searches for the image when `q` is not sent.
- **Localized results**: control the interface language with `hl` and the result country, prices, and currencies with `gl`.

---

## Endpoint

```
GET https://api.scrape.do/plugin/google/lens
```

---

## Request Parameters

### Required

| Parameter | Type | Description |
|-----------|------|-------------|
| `token` | string | Your Scrape.do API authentication token |
| `url` | string | Public `http` or `https` URL of the image to search. The image must be reachable by Google |

### Search

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `type` | string | `all` | Result type: `all` returns visual results and related searches, `visual` returns visual results only, and `exact` returns pages containing the exact image |
| `q` | string | - | Optional text to search with the image, such as a color or product detail. Not supported with `type=exact` |
| `safe` | string | Google's default | `active` filters explicit results; `off` disables the filter |

### Localization

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `hl` | string | `en` | Interface language, for example `en`, `de`, `fr`, `ja`, or `tr` |
| `gl` | string | `us` | Two-letter ISO 3166-1 country code, for example `us`, `gb` (not `uk`), `de`, or `jp`. Controls the market Google uses for results, prices, and currencies |

### Output

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `include_html` | boolean | `false` | Set to `true` or `1` to include the Google Lens results page in the `html` response field at no extra cost |

---

## Example Usage

### Visual Matches and Related Searches

```bash
curl -G "https://api.scrape.do/plugin/google/lens" \
  --data-urlencode "token=$TOKEN" \
  --data-urlencode "url=https://m.media-amazon.com/images/I/61bK6PMOC3L._AC_SL1500_.jpg"
```

### Refine an Image Search with Text

```bash
curl -G "https://api.scrape.do/plugin/google/lens" \
  --data-urlencode "token=$TOKEN" \
  --data-urlencode "url=https://m.media-amazon.com/images/I/61bK6PMOC3L._AC_SL1500_.jpg" \
  --data-urlencode "q=blue"
```

### Exact-Image Matches

```bash
curl -G "https://api.scrape.do/plugin/google/lens" \
  --data-urlencode "token=$TOKEN" \
  --data-urlencode "url=https://m.media-amazon.com/images/I/61bK6PMOC3L._AC_SL1500_.jpg" \
  --data-urlencode "type=exact"
```

---

## Response

### Visual Results

Returned for `type=all` and `type=visual`. A typical search returns about 60 results.

```json
{
  "search_parameters": {
    "image_url": "https://m.media-amazon.com/images/I/61bK6PMOC3L._AC_SL1500_.jpg",
    "type": "all",
    "hl": "en",
    "gl": "us"
  },
  "visual_results": [
    {
      "position": 1,
      "title": "Amazon.com: Apple iPhone 14, 128GB, Blue for T-Mobile ...",
      "link": "https://www.amazon.com/Apple-iPhone-128GB-T-Mobile-Renewed/dp/B0BN746959",
      "source": "Amazon.com",
      "domain": "www.amazon.com",
      "price": "$350*",
      "extracted_price": 350,
      "currency": "$",
      "rating": 4.3,
      "reviews": 2076,
      "in_stock": true,
      "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:...",
      "image": {
        "link": "https://m.media-amazon.com/images/I/61aEBeER-+L._AC_UF894,1000_QL80_.jpg",
        "width": 755,
        "height": 1000
      }
    }
  ],
  "related_searches": [
    {
      "query": "Apple iPhone 14",
      "link": "https://www.google.com/search?q=Apple+iPhone+14&kgmid=/g/11s7qfcm0s&..."
    }
  ]
}
```

#### `search_parameters`

Shows the parameters used for the search: `image_url`, `type`, `q`, `hl`, `gl`, and `safe`. Optional `q` and `safe` fields appear only when sent. The response always includes the effective `type`, `hl`, and `gl`, including their defaults.

#### `visual_results[]`

| Field | Type | Description |
|-------|------|-------------|
| `position` | integer | 1-based result position |
| `title` | string | Title of the page showing the image |
| `link` | string | URL of the page |
| `source` | string | Site name |
| `domain` | string | Site domain |
| `price` | string | Price as Google displays it. An asterisk is Google's marker for a price it may not have verified |
| `extracted_price` | number | Numeric value parsed from `price` |
| `currency` | string | Currency symbol or code shown with the price |
| `rating` | number | Product rating out of 5, when available |
| `reviews` | integer | Number of reviews associated with the rating, when available |
| `in_stock` | boolean | Stock status when shown. Available only for English results that include stock information |
| `thumbnail` | string | Matching image thumbnail URL |
| `image` | object | Full-size matching image with `link`, `width`, and `height` in pixels |

When Google finds no visual match or cannot load the supplied image, the request can still succeed without a `visual_results` field.

#### `related_searches[]`

Returned only for `type=all` without `q`.

| Field | Type | Description |
|-------|------|-------------|
| `query` | string | Related search Google suggests for the image |
| `link` | string | Google Search URL for the suggested query |

### Exact Results

With `type=exact`, the response contains `exact_results` instead of `visual_results` and `related_searches`.

```json
{
  "search_parameters": {
    "image_url": "https://m.media-amazon.com/images/I/61bK6PMOC3L._AC_SL1500_.jpg",
    "type": "exact",
    "hl": "en",
    "gl": "us"
  },
  "exact_results": [
    {
      "position": 1,
      "title": "Apple iPhone 14 A2649 Unlocked 256GB Blue Good - eBay",
      "link": "https://www.ebay.com/itm/...",
      "source": "eBay",
      "price": "$315.26",
      "extracted_price": 315.26,
      "currency": "$",
      "in_stock": true,
      "image_size": {
        "width": 756,
        "height": 1000
      }
    }
  ]
}
```

An image used widely returns up to 400 exact matches. If Google finds no page containing the exact image, the request can still succeed without an `exact_results` field.

| Field | Type | Description |
|-------|------|-------------|
| `position` | integer | 1-based result position |
| `title` | string | Title of the page containing the image |
| `link` | string | URL of the page. The first 50 of up to 400 results are resolved page URLs; later results and links that cannot be resolved in time may remain Google redirect URLs |
| `source` | string | Site name |
| `price` | string | Price as Google displays it, when available |
| `extracted_price` | number | Numeric value parsed from `price` |
| `currency` | string | Currency symbol or code shown with the price |
| `in_stock` | boolean | Stock status when Google shows it. Available only for English results |
| `image_size` | object | Width and height of the image on the result page, in pixels |

> [!NOTE]
> Use the [Google Redirect (Goto) Link Resolver](/documentation/google-scraper-api/goto) to resolve an `exact_results[].link` that starts with `https://www.google.com/goto?url=`. Resolving links returned after the first 50 exact matches costs 1 credit per link.

### HTML

When `include_html=true`, the response also includes `html` with the results page exactly as Google served it. This field is included even when the search finds no matches.

Links in `html` remain Google redirect URLs and are not replaced with the resolved links from `exact_results`. A typical results page is 0.7 to 1.3 MB and is usually smaller when no results match.

---

## Usage Notes

- The image URL must be publicly reachable by Google. Hosts that block Google from fetching images can produce a successful response with no result array.
- `type=all` and `type=visual` usually complete in about 5 seconds.
- `type=exact` usually takes about 20 seconds and can take up to about 35 seconds because page links are resolved before the response is returned.
- Results come from one live search. Repeating the same request can return a different result set.
- `q` cannot be combined with `type=exact`.
- A two-letter code that is not a country, such as `uk` or `en`, is not rejected up front. The request fails with `502` after about a minute. Use ISO 3166-1 codes such as `gb` for the United Kingdom.

---

## Error Handling

| Status | Body | Cause |
|--------|------|-------|
| `400` | `{ "error": "token is required" }` | The `token` parameter is missing |
| `400` | `{ "error": "url must be the http(s) URL of an image" }` | `url` is missing or is not an `http` or `https` URL |
| `400` | `{ "error": "type must be all, visual or exact" }` | `type` has an unsupported value |
| `400` | `{ "error": "q is not supported with type exact" }` | `q` was sent with `type=exact` |
| `400` | `{ "error": "safe must be active or off" }` | `safe` has an unsupported value |
| `400` | `{ "error": "gl must be a two-letter country code" }` | `gl` is not two letters |
| `400` | `{ "error": "include_html must be true or false" }` | `include_html` is not a boolean value |
| `401` / `402` | Standard API error | The token is invalid or the account does not have enough credits |
| `502` | `{ "error": "request failed", "message": "Please try again, and if the issue continues, contact support." }` | The search could not be completed. Retry the request |

---