Google Images with the Google Search API: A Practical Guide

TL;DR:

• Use Google Search API for image-search discovery with tbm=isch. The request uses the same authenticated endpoint and scraper.google.search actor as web search.
• Inspect image data before designing an exporter. The example saves the complete response and prints its structure without assuming an unverified image-result schema.
• Search visibility and image reuse are separate. A search result can help locate an image; the source page and license determine the next steps for using it.

An image-search workflow starts with discovery: find candidate images for a query, inspect the sources, and decide which records belong in a research dataset. A useful integration preserves that trail instead of downloading files immediately and losing the pages that explain them.

This guide uses the Google Images API scenario within Scrapeless Google Search API. It covers the request settings, a complete Python capture script, and the checks needed before turning the returned data into an image catalog. It does not assume that a web-result field map also describes image results.

What You Can Do With Image Search Data

Image search can support visual research, content discovery, and review of how a topic appears across public sources. For example, an architecture researcher can search for a building type, identify relevant source pages, and review the images and surrounding descriptions together.

The API supplies search data for your application to inspect. It does not automatically create an asset library, verify every image's origin, or grant permission to republish a file. Those steps belong in the workflow you build around discovery.

Keep the query and market context with the response. A visual research set for one country or language may differ from another. Without the input record, later reviewers cannot tell which search produced a candidate image.

Select Google Images With tbm=isch

Use POST https://api.scrapeless.com/api/v1/scraper/request, authenticate with x-api-token, and set actor to scraper.google.search. Put tbm="isch" inside input beside the query.

The parameter reference documents this image-search selector. The same input model includes gl for country, hl for language, and location controls. Choose either location or uule if you need a specific origin.

If you use a complete url instead, the other input parameters are ignored. That includes a separately supplied image selector. Use one input mode and verify that the URL itself expresses the intended image search before sending it.

Prerequisites for the Capture Script

Prepare Python, install requests with python3 -m pip install requests, and make a Scrapeless API key available through SCRAPELESS_API_KEY. The script also needs permission to write a local JSON file. Standard-library modules handle serialization, timestamps, and paths.

The authenticated request requires your own account key and has not been executed with a live account for this article. The documented request shape is verified; a complete image-response schema is not asserted here. Save the example as capture_google_images.py and run python3 capture_google_images.py when the key is configured.

The Requests HTTP client sends the JSON request. The example stops after capture and structural inspection; it does not retrieve pending task results or download image files.

Capture the Full Response in Python

The query modern library architecture provides a concrete visual research example. Change it to a topic relevant to your project while retaining the country, language, and result-type settings in the saved record.

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

search_input = {"q": "modern library architecture", "gl": "us", "hl": "en", "tbm": "isch"}
response = requests.post(
    "https://api.scrapeless.com/api/v1/scraper/request",
    headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    json={"actor": "scraper.google.search", "input": search_input},
    timeout=120,
)
response.raise_for_status()
payload = response.json()
received_at = datetime.now(timezone.utc).isoformat()
run_id = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
output = Path(f"google-images-{run_id}.json")
output.write_text(json.dumps({
    "input": search_input, "http_status": response.status_code,
    "received_at": received_at, "response": payload,
}, ensure_ascii=False, indent=2), encoding="utf-8")

if response.status_code == 201:
    print(f"Task pending; inspect taskId in {output}.")
elif response.status_code == 200 and isinstance(payload, dict):
    print(f"Saved {output}. Top-level response fields:")
    for key, value in payload.items():
        print(key, type(value).__name__)
        if isinstance(value, list):
            print("  items:", len(value))
            if value and isinstance(value[0], dict):
                print("  first-item keys:", sorted(value[0]))
else:
    raise ValueError(f"Unexpected response; inspect {output}.")

The outer input, http_status, received_at, and response keys form this application's record. They are separate from the returned API schema. The filename includes a client-generated identifier, and the receipt time is recorded on the local machine.

The JSON serialization module preserves the complete nested payload. The terminal inspection lists top-level types and first-item keys for any top-level arrays. It is an initial inspection aid; arrays nested inside objects still require review in the saved JSON.

Start Scraping with Scrapeless

Power up your web scraping and automation workflow with Scrapeless!
Sign up today and get $5 in free credit — no credit card required.

Claim your free credit now in the Scrapeless Dashboard.

Establish the Image Fields Before Flattening Them

The capture step deliberately avoids indexing a guessed images_results field. The current image endpoint reference includes a response example with web-search modules, so it does not establish a complete image-specific mapping. Use a successful response from your account to confirm the array paths and item fields your application will consume.

Inspect several returned items rather than assuming the first item represents every record. Note which values are optional, which are nested, and whether a missing value is absent or explicitly null. Keep those distinctions while designing your exporter.

The following are proposed application columns, not claimed API field names:

Keep the source page and image resource separate. They answer different questions: one provides context for review, while the other may identify image bytes. A preview should not be silently substituted for a full image asset.

Recognize Pending Tasks and Unexpected Shapes

The request workflow defines HTTP 200 as a data response and HTTP 201 as a task in progress with a taskId. The script saves both, then applies structural inspection only to a completed object response.

A pending task should not become an empty image dataset. Likewise, a response containing unfamiliar modules should prompt inspection before an exporter invents empty columns. Preserve the diagnostic record so the request and payload can be reviewed together.

If you add filters or change the search origin, compare a small set of responses before expanding collection. Search type and filter changes can affect which modules appear. The exact output rows are therefore established by observation, not by a fixed example table in a tutorial.

Review Image Context and Reuse Rights

Image search helps find material, but it does not establish a license for that material. Follow the candidate's source page and examine the publisher's usage conditions before copying, redistributing, or modifying an image.

Google's image license metadata can expose license and acquisition information in supported image-search experiences. Presence in search alone does not prove those permissions exist. Its image usage-rights guidance explains why license details should be checked at the source.

For a research catalog, keep a separate review state such as unreviewed or permission confirmed, with the source and review evidence your team requires. Those are application decisions, not API guarantees. Avoid marking an image reusable merely because a request succeeded.

Extend Discovery Into a Reviewable Catalog

After confirming the response mapping, create a small export and compare it with the saved payload. Confirm that each source page belongs to the same candidate as the image reference and title. Then decide what counts as a duplicate for your use case.

Two results can point to the same image through different pages, or to different versions of a similar image. URL deduplication and visual similarity are different operations. Start with a documented rule and preserve the original references before introducing transformations.

If your application later fetches source pages or image files, make that a separate stage with its own outcome. That separation allows a candidate to remain in the research record even when a later retrieval or permission review has not completed.

Conclusion

Use tbm=isch to request image search, preserve the response, and confirm its fields before creating an exporter. A useful image research workflow keeps source context and permission review alongside discovery, so each selected asset has a traceable path back to its origin.

Ready to Build Your Search Data Workflow?

Connect with developers building search workflows in our community: Discord · Telegram.

Use the Google Search API documentation to configure your first request. Check Scrapeless pricing when planning your workload, and use the Python search tutorial for related background. This guide's API examples use the current request interface.

FAQ

Q: Is Google Images a separate actor in this example?

No. This documented request uses scraper.google.search with tbm=isch in the input.

Q: Does the code download image files?

No. It captures search data and inspects its structure. Downloading an image would be a separate application step.

Q: Can the web-search organic-results mapping be reused unchanged?

Do not assume so. Inspect actual image-search data and confirm the relevant array paths and item fields first.

Q: Why is there no fixed image JSON sample?

The current reference example does not establish a complete image-specific schema. This guide provides a capture workflow without presenting an invented response as real output.

Q: Does a returned image have a reusable license?

Search appearance does not establish reuse rights. Review the source page and applicable license or permission before using the image.