Skip to content

About

Google Images API: scrape Google Images results as structured JSON (position, title, site, page URL and image file URL, related searches) for any keyword, country and language, up to 700 images per request. Python, Node.js, Go, PHP and cURL examples.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

Google Images API

Semust Google Images API: Google Images results as JSON

Get API key Documentation MCP server License: MIT

The Semust Google Images API returns Google Images results as clean, structured JSON: every image's position, title, site name, the page it appears on and the URL of the image file itself, plus related searches when Google shows them. Send a keyword, a country and a language, and collect up to 700 images in one request. No proxies, CAPTCHAs or HTML parsing on your side.

It is built for SEO teams and developers who need image SEO audits, visual competitor research, brand monitoring and image datasets. The API is part of the Semust SEO platform.

How it works

Your code sends POST /v1/google-images to Semust and receives Google Images results as JSON. Long requests return 202 and are collected from /v1/tasks.

1. Get your API credentials

Create an API user on the Semust API access page. You get a username and a password. Every request sends them as two headers:

Header Value
SEMUST-API-USER Your API username
SEMUST-API-PASSWORD Your API password

The examples in this repository read them from environment variables, so they never end up in your code:

export SEMUST_API_USER="your_username"
export SEMUST_API_PASSWORD="your_password"

Tip

There is no subscription. You top up a prepaid balance and pay only for successful requests; failed requests are refunded automatically. Prices are on the Google Images API page.

2. Send a request

import os, time, requests

HEADERS = {
    "SEMUST-API-USER": os.environ["SEMUST_API_USER"],
    "SEMUST-API-PASSWORD": os.environ["SEMUST_API_PASSWORD"],
}

resp = requests.post(
    "https://data.semust.com/v1/google-images",
    params={"wait": 60},
    headers=HEADERS,
    json={"keyword": "seo dashboard", "country": "US", "language": "en", "depth": 20},
    timeout=90,
)
while resp.status_code == 202:  # still running: poll the task
    time.sleep(int(resp.headers.get("Retry-After", 5)))
    resp = requests.get(resp.json()["poll_url"], headers=HEADERS, timeout=30)

for image in resp.json().get("images", []):
    print(image["position"], image["title"], image["source_url"])

3. Run the examples

Language File Run
Python examples/python/images.py python images.py "seo dashboard"
Python, image source counter examples/python/image_sources.py python image_sources.py "seo dashboard" "seo report template"
Node.js 18+ examples/node/images.mjs node images.mjs "seo dashboard"
Go examples/go/main.go go run . "seo dashboard"
PHP examples/php/images.php php images.php "seo dashboard"
cURL examples/curl/images.sh ./images.sh

Request parameters

POST https://data.semust.com/v1/google-images with a JSON body:

Parameter Type Default Description
keyword (required) string – The image search query, exactly as a user would type it.
country string US Results country, ISO 3166-1 alpha-2 (US, GB, DE, TR, …).
language string en Interface language, ISO 639-1 (en, de, tr, …).
depth integer 100 How many images to collect, 1–700. Images are collected in blocks of 100, so the response can hold more than depth images, up to the end of the block. You are never billed for more blocks than depth covers.
Query parameter Default Description
wait 60 Seconds to hold the connection before answering 202, 0–80. 0 answers 202 at once (fire and collect).
Header Description
Idempotency-Key Optional, up to 128 characters. Repeating a request with the same key returns the same task and is charged once.

Output sample

Google Images results for "seo dashboard" returned by the Semust Google Images API

A shortened response for {"keyword": "seo dashboard", "country": "US", "language": "en", "depth": 20}. Lists are cut to two items; the complete response is in output-google-images-scraper.json.

{
  "success": true,
  "result_count": 100,
  "keyword": "seo dashboard",
  "country": "US",
  "language": "en",
  "images": [
    {
      "position": 1,
      "title": "SEO Dashboard Examples | Geckoboard",
      "subtitle": "Geckoboard",
      "alt": "SEO Dashboard Examples | Geckoboard",
      "url": "https://www.geckoboard.com/dashboard-examples/marketing/seo-dashboard/",
      "source_url": "https://www.geckoboard.com/uploads/SEO-audit-dashboard.png"
    },
    {
      "position": 2,
      "title": "SEO Dashboard Template | Client Reporting & Performance Monitoring |  Whatagraph",
      "subtitle": "Whatagraph",
      "alt": "SEO Dashboard Template | Client Reporting & Performance Monitoring |  Whatagraph",
      "url": "https://whatagraph.com/templates/seo-dashboard",
      "source_url": "https://media.whatagraph.com/Hero_SEO_Dashboard_Template_a958c5b551.png?width=992"
    }
  ]
}

subtitle, alt and related_searches only appear when Google shows them for the query.

JSON output structure

Top-level fields

Field Type Description
success boolean true for a successful search.
result_count integer Number of images in images.
keyword, country, language string The request as it was run, with defaults filled in.
images array Image results, in the order Google Images shows them.
related_searches array Related searches Google suggests for the query, each with title and url. Left out when there are none.

Image result

Field Type Description
position integer Position in Google Images, starting at 1.
title string Title shown with the image, usually the title of the page it comes from.
subtitle string Site name shown under the image, such as Geckoboard.
alt string Alt text Google lists for the image. Often the same as title.
url string The page the image appears on.
source_url string Direct URL of the image file.

Long-running requests (202 and polling)

Most requests finish in a few seconds and return 200 with the result. If a request is still running after wait seconds (60 by default, maximum 80), the API returns 202 Accepted with a task_id instead. Nothing is lost and you are not charged twice:

  1. Read task_id from the body (also in the X-Task-Id header).
  2. Wait Retry-After seconds.
  3. Call GET https://data.semust.com/v1/tasks/{task_id} with the same headers until the status is no longer 202. The final answer is exactly what the original request would have returned.

Every example in examples/ already handles this. Results stay available for 72 hours, and fetching them again is free. Set your HTTP client's read timeout above wait (for example wait + 30 seconds). Send an Idempotency-Key header to retry a request safely without paying twice. Details: Tasks & long-running requests.

Errors

Errors return JSON with a readable error and a stable code. Failed requests are not charged.

HTTP code Meaning
200 EMPTY_RESULTS Google Images returned nothing for this query. The body has error and code instead of images. Not charged.
400 INVALID_REQUEST, KEYWORD_REQUIRED The body is malformed, depth is outside 1–700, or keyword is missing.
401 MISSING_CREDENTIALS, INVALID_CREDENTIALS, CREDENTIALS_EXPIRED Check the two auth headers.
402 INSUFFICIENT_CREDITS Your balance does not cover the blocks depth asks for. Top up or lower depth.
403 IP_NOT_WHITELISTED Your API user only accepts requests from listed IP addresses.
429 RATE_LIMIT_EXCEEDED Slow down; the default limit is 60 requests per minute.
503 WORKER_FAILED, TIMEOUT Temporary failure. Retry with the same Idempotency-Key.

Pricing

$0.0022 per started block of 100 images returned, never more blocks than depth covers. The price of every block in depth is reserved when the request starts and the unused part is refunded when it finishes: depth: 150 costs $0.0022 when 37 images come back and $0.0044 when 150 or more do. Repeating the same request (keyword, country, language and depth) within 24 hours is answered from cache at no charge. Failed requests and searches with no images are refunded automatically. Current prices are on the Google Images API page.

Use cases

  1. Image SEO audits. Check whether your images appear for your target keywords, at which position, and which of your pages Google attributes them to.
  2. Visual competitor research. See which sites own the image results for a topic and how often each one appears. Start from image_sources.py.
  3. Brand and asset monitoring. Find the pages that show your product screenshots, logos or infographics, and spot sites reusing them.
  4. Content and design research. Collect the titles and reference images that rank for a query before you brief a designer or plan a visual.
  5. Datasets and AI agents. Build labelled lists of image URLs, titles and source pages for research, evaluation sets or an agent that needs visual search results.

Why Semust

  • Pay as you go. No monthly plan or minimum commitment for the API. Top up once, pay per successful request, and get failed requests refunded automatically.
  • One account, every SEO dataset. SERP, keyword data, backlinks, domain research, YouTube, Google Trends, Lighthouse and Google Business data use the same credentials, the same error format and the same task system.
  • Any country, any language. Localised results for every Google market, including strong coverage of Türkiye and Turkish-language queries.
  • Built for AI workflows. Plug the same data into Claude, Cursor or ChatGPT with the open-source Semust MCP server.

FAQ

Is scraping Google Images legal?

Search results are publicly available, and collecting public data is generally lawful in many jurisdictions. The images themselves belong to their owners: the API returns URLs and metadata, and reusing an image needs the owner's permission or a suitable license. Laws differ by country, so check the rules that apply to you or ask a lawyer. This is not legal advice.

How many images does one request return?

Up to 700. Set depth to the number you need; images are collected in blocks of 100, and you pay per started block that comes back.

Does the API download the image files?

No. Each result has source_url, the direct link to the image file, and url, the page it appears on. Download the files yourself if you have the right to use them.

Can I get results for a specific country or language?

Yes. Set country to any ISO 3166-1 alpha-2 code and language to an ISO 639-1 code. Image results differ between markets, so query the one your audience uses.

Am I charged again for the same search?

Not within 24 hours. A repeat of the same keyword, country, language and depth is answered from cache for free.

Can I use it from Claude, ChatGPT or Cursor?

Yes, through a tool your agent can call: the Python example is a ready-made starting point. The Semust MCP server also connects AI assistants to your Semust account data; see Semust MCP for what it covers.

Learn more

Related repositories

SEO data APIs

Repository What it does Product page
google-serp-scraper Organic results, People Also Ask, AI Overviews, ads and more as JSON Google SERP API
youtube-scraper YouTube search, video details, transcripts and comments YouTube API
google-trends-scraper Interest over time, regions, related queries and demographics Google Trends API
google-business-scraper Google Business profiles, local search and reviews Google Business Data API
keyword-research-api Search volume, CPC, competition, intent and related keywords Keyword Research API
backlinks-api Backlinks, referring domains, anchors and link history Backlinks API
domain-research-api Organic keywords, competitors, top pages and keyword gaps for any domain Domain Research API
technical-seo-api 27 technical SEO checks for any URL in one call Technical SEO API
lighthouse-on-page-api Lighthouse scores, on-page audits and page content extraction Lighthouse & On-Page API

MCP servers for AI assistants

Repository What it does Product page
semust-mcp One MCP server for Search Console, GA4, Google Ads, rank tracking and social posting Semust MCP Server
seo-mcp Search Console, rank tracking, indexing and competitor tools for AI assistants SEO MCP
google-search-console-mcp Ask your AI assistant about clicks, queries and pages Google Search Console MCP
google-analytics-mcp GA4 traffic, channels and conversions in your AI assistant Google Analytics MCP
google-ads-mcp Campaigns, search terms and spend in your AI assistant Google Ads MCP
rank-tracker-mcp Keyword rankings and AI-search visibility for AI assistants Rank Tracker MCP
web-analytics-mcp Privacy-friendly first-party analytics in your AI assistant Web Analytics MCP
bing-webmaster-mcp Bing queries, pages, links and crawl issues Bing Webmaster MCP
yandex-metrica-mcp Yandex Metrica traffic and search phrases Yandex Metrica MCP
social-media-mcp Draft and schedule LinkedIn, Facebook and Instagram posts Social Media MCP

Support

Found a problem with an example? Open an issue.

License

The code examples in this repository are released under the MIT License. Use of the Semust API is subject to the Semust Terms of Service.

About

Google Images API: scrape Google Images results as structured JSON (position, title, site, page URL and image file URL, related searches) for any keyword, country and language, up to 700 images per request. Python, Node.js, Go, PHP and cURL examples.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors