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.
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.
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"])| 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 |
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. |
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.
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. |
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:
- Read
task_idfrom the body (also in theX-Task-Idheader). - Wait
Retry-Afterseconds. - Call
GET https://data.semust.com/v1/tasks/{task_id}with the same headers until the status is no longer202. 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 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. |
$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.
- Image SEO audits. Check whether your images appear for your target keywords, at which position, and which of your pages Google attributes them to.
- Visual competitor research. See which sites own the image results for a topic and how often each one appears. Start from
image_sources.py. - Brand and asset monitoring. Find the pages that show your product screenshots, logos or infographics, and spot sites reusing them.
- Content and design research. Collect the titles and reference images that rank for a query before you brief a designer or plan a visual.
- 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.
- 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.
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.
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.
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.
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.
Not within 24 hours. A repeat of the same keyword, country, language and depth is answered from cache for free.
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.
- Google Images API documentation · Turkish documentation
- Image SEO guide (Turkish)
- Free image extractor
- What is a web scraping API? (Turkish)
- Best SERP API alternatives
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 |
- Email: destek@semust.com
- Contact form
- LinkedIn · YouTube · Instagram
Found a problem with an example? Open an issue.
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.

