Skip to content
Scrappa Get API key
Google Lens API 1 credit / request

Google Lens Image Upload

POST https://scrappa.co/api/google/lens

Send the image as the multipart field image or as image_base64 (raw base64 or a data URI), not both. The maximum size is 10 MB. JPEG, PNG, WebP, GIF and AVIF are accepted. The image is resized to at most 1600 px, converted to JPEG and stripped of EXIF data. It is kept at most 15 minutes and deleted right after the search. The response has the same visual_matches, exact_matches, and related_content arrays as the URL search. search_parameters.url is null and search_parameters.image is upload.

Google Lens Image Upload 1 credit / request

Endpoint

Request preview
POST
https://scrappa.co/api/google/lens
Auth header
x-api-key
Cost
1 credit / request
Response preview
200 OK
{
    "search_parameters": {
        "url": null,
        "image": "upload",
        "q": null,
        "type": "visual_matches"
    },
    "visual_matches": [
        {
            "source": "Wikipedia",
            "title": "Coffee cup",
            "link": "https://en.wikipedia.org/wiki/Coffee",
            "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:example",
            "price": null,
...

Parameters

Start with the required fields, then add optional filters only when your use case needs them.

Runnable path

This endpoint has no required query parameters.

4 optional filters available.

image file Optional

Image file as a multipart form field. Send this or image_base64.

Example value example
image_base64 string Optional

Base64 encoded image or a data:image/...;base64, URI. Send this or image.

Example value example
q string Optional

Optional text used to refine visual or product matches.

Example value coffee shops
type string Optional

One of all, products, exact_matches, or visual_matches.

Example value example

Response Schema

Example response fields are illustrative; inspect the JSON before integrating.

Example response fields

Scan these fields before integrating.

search_parameters visual_matches exact_matches related_content

Common visual_matches fields

source title link thumbnail
JSON Response
200 OK
{
    "search_parameters": {
        "url": null,
        "image": "upload",
        "q": null,
        "type": "visual_matches"
    },
    "visual_matches": [
        {
            "source": "Wikipedia",
            "title": "Coffee cup",
            "link": "https://en.wikipedia.org/wiki/Coffee",
            "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:example",
            "price": null,
            "position": 1
        }
    ],
    "exact_matches": [],
    "related_content": []
}

Errors

Handle these documented responses before retrying or showing customer-facing failures.

422

HTTP 422

Upload only (POST). The file is not a JPEG, PNG, WebP, GIF or AVIF image that can be decoded. Not billed. Retrying the same file does not help.

{
    "error": "The uploaded file is not a valid JPEG, PNG, WebP, GIF or AVIF image.",
    "retryable": false,
    "error_code": "INVALID_IMAGE_UPLOAD"
}
422

HTTP 422

Google Lens reported that it could not load the image. Not billed. Retrying the same URL does not help.

{
    "error": "Google Lens could not load a valid image from the supplied URL.",
    "retryable": false,
    "error_code": "INVALID_IMAGE"
}
422

HTTP 422

Google Lens returned an empty result page. This usually means Google could not download the image (HTTP error, hotlink or bot protection, or an expired signed URL). Not billed. Retrying the same URL does not help; use a URL that loads publicly.

{
    "error": "Google Lens returned no matches for this image. Google usually shows this when it cannot download the image (HTTP error, hotlink or bot protection, or an expired signed URL). Check that the URL loads publicly, or use a different image URL.",
    "retryable": false,
    "error_code": "IMAGE_NOT_PROCESSED"
}
503

HTTP 503

Google blocked the request. Not billed and retryable.

{
    "error": "Google Lens blocked the visual search request.",
    "retryable": true,
    "error_code": "GOOGLE_LENS_BLOCKED"
}
503

HTTP 503

Google returned an unexpected result layout. Not billed and retryable.

{
    "error": "Google Lens returned an unexpected result layout.",
    "retryable": true,
    "error_code": "PARSE_DRIFT"
}
503

HTTP 503

The upstream service is temporarily unavailable. Please retry shortly.

{
    "error": "The upstream service is temporarily unavailable. Please retry shortly.",
    "retryable": true,
    "error_code": "upstream_unavailable"
}

Generate Code with AI

Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.

Try It Live

Test this endpoint in our interactive playground with real data.