API Platform
Google Images API
Search Google Images programmatically. Retrieve image results with titles, URLs, source pages, and related searches for any keyword, language, and country.
Search Google Images programmatically. Retrieve image results with titles, URLs, source pages, and related searches for any keyword, language, and country.
Product page: Google Images API.
Authentication
All requests require header-based authentication. Include your API credentials in every request.
| Header | Type | Description |
|---|---|---|
SEMUST-API-USER | string | Your API user's username |
SEMUST-API-PASSWORD | string | Your API user's password |
Create API credentials from the API Access page.
SEMUST-API-USER: your_username
SEMUST-API-PASSWORD: your_passwordRequest Parameters
Send a application/json body with the following parameters:
Body
keywordstringrequiredThe search query for Google Images (e.g., "istanbul manzara", "modern architecture").
languagestringdefault: enLanguage code (ISO 639-1). Controls the language of search results. Examples: "en", "tr", "de", "fr", "es".
countrystringdefault: USCountry code (ISO 3166-1 alpha-2). Geo-targets image results to a specific country. Examples: "US", "TR", "DE", "GB".
depthintegerdefault: 100Number of image results to return. Minimum: 1, Maximum: 700. Default: 100. Higher values return more results but may increase cost.
Depth Limit
The depth parameter must be between 1 and 700. Higher values return more images but increase processing time and cost.
{
"keyword": "istanbul manzara",
"language": "tr",
"country": "TR",
"depth": 10
}Code Examples
Complete examples showing how to search Google Images in different languages.
curl -X POST https://data.semust.com/v1/google-images \
-H "Content-Type: application/json" \
-H "SEMUST-API-USER: your_username" \
-H "SEMUST-API-PASSWORD: your_password" \
-d '{
"keyword": "istanbul manzara",
"language": "tr",
"country": "TR",
"depth": 10
}'import requests
response = requests.post(
"https://data.semust.com/v1/google-images",
headers={
"SEMUST-API-USER": "your_username",
"SEMUST-API-PASSWORD": "your_password",
},
json={
"keyword": "istanbul manzara",
"language": "tr",
"country": "TR",
"depth": 10,
},
)
if response.status_code == 200:
data = response.json()
print(f"Found {data['result_count']} images")
for img in data.get("images", []):
print(f"{img['position']}. {img['title']}")
print(f" URL: {img['url']}")
print(f" Source: {img['source_url']}")
else:
print(f"Error [{response.status_code}]: {response.text}")const response = await fetch("https://data.semust.com/v1/google-images", {
method: "POST",
headers: {
"Content-Type": "application/json",
"SEMUST-API-USER": "your_username",
"SEMUST-API-PASSWORD": "your_password",
},
body: JSON.stringify({
keyword: "istanbul manzara",
language: "tr",
country: "TR",
depth: 10,
}),
});
if (response.ok) {
const data = await response.json();
console.log(`Found ${data.result_count} images`);
data.images?.forEach((img) => {
console.log(`${img.position}. ${img.title}`);
console.log(` URL: ${img.url}`);
console.log(` Source: ${img.source_url}`);
});
} else {
const text = await response.text();
console.error(`Error [${response.status}]: ${text}`);
}package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
func main() {
payload := map[string]interface{}{
"keyword": "istanbul manzara",
"language": "tr",
"country": "TR",
"depth": 10,
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST",
"https://data.semust.com/v1/google-images",
bytes.NewBuffer(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("SEMUST-API-USER", "your_username")
req.Header.Set("SEMUST-API-PASSWORD", "your_password")
resp, err := (&http.Client{}).Do(req)
if err != nil {
fmt.Printf("Request failed: %v\n", err)
return
}
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
if resp.StatusCode == 200 {
var data map[string]interface{}
json.Unmarshal(respBody, &data)
if images, ok := data["images"].([]interface{}); ok {
for _, item := range images {
img := item.(map[string]interface{})
fmt.Printf("%v. %v\n", img["position"], img["title"])
fmt.Printf(" URL: %v\n", img["url"])
fmt.Printf(" Source: %v\n", img["source_url"])
}
}
} else {
fmt.Printf("Error %d: %s\n",
resp.StatusCode, string(respBody))
}
}<?php
$payload = json_encode([
"keyword" => "istanbul manzara",
"language" => "tr",
"country" => "TR",
"depth" => 10,
]);
$ch = curl_init("https://data.semust.com/v1/google-images");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"SEMUST-API-USER: your_username",
"SEMUST-API-PASSWORD: your_password",
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
$data = json_decode($response, true);
echo "Found " . $data["result_count"] . " images\n";
foreach ($data["images"] ?? [] as $img) {
echo $img["position"] . ". " . $img["title"] . "\n";
echo " URL: " . $img["url"] . "\n";
echo " Source: " . $img["source_url"] . "\n";
}
} else {
echo "Error [{$httpCode}]: {$response}\n";
}Response
Returns a JSON object with image results and related search suggestions.
Response Fields
| Field | Type | Description |
|---|---|---|
success | boolean | Always true on successful response |
result_count | integer | Number of images returned |
keyword | string | The search keyword used |
country | string | The country used for search |
language | string | The language used for search |
images | array | Array of image result objects |
related_searches | array | Related search suggestions (may be empty) |
Image Object Fields
| Field | Type | Description |
|---|---|---|
position | integer | Position/rank of the image in results (1-indexed) |
title | string | Title or name of the image |
subtitle | string | Additional subtitle or description |
alt | string | Alt text for the image |
url | string | Direct URL to the image file |
source_url | string | URL of the webpage containing the image |
Related Search Fields
| Field | Type | Description |
|---|---|---|
title | string | Suggested related search term |
url | string | URL for the related search (may be empty) |
{
"success": true,
"result_count": 10,
"keyword": "istanbul manzara",
"country": "TR",
"language": "tr",
"images": [
{
"position": 1,
"title": "İstanbul Boğazı Manzarası",
"subtitle": "Galata Kulesi'nden çekilmiş",
"alt": "Istanbul Bosphorus view at sunset",
"url": "https://example.com/images/istanbul-bosphorus.jpg",
"source_url": "https://example.com/istanbul-photos"
},
{
"position": 2,
"title": "İstanbul Silueti",
"subtitle": "",
"alt": "Istanbul skyline panorama",
"url": "https://example.com/images/istanbul-skyline.jpg",
"source_url": "https://example.com/travel-gallery"
}
],
"related_searches": [
{
"title": "istanbul gece manzarası",
"url": ""
},
{
"title": "istanbul boğaz manzarası",
"url": ""
}
]
}Error Codes
All errors return a JSON object with a human-readable message and an error code.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | INVALID_REQUEST | Request body is malformed or missing required fields |
| 400 | KEYWORD_REQUIRED | The keyword field is empty or missing |
| 401 | INVALID_API_KEY | Authentication failed — invalid username or password |
| 402 | INSUFFICIENT_CREDITS | Your account does not have enough credits |
| 200 | EMPTY_RESULTS | No image results found for this query |
| 500 | INTERNAL_ERROR | An internal server error occurred |
| 502 | WORKER_FAILED | Failed to fetch Google Images results from the worker |
| 504 | TIMEOUT | The request timed out (max 10 minutes) |
{
"error": "Your account does not have enough credits",
"code": "INSUFFICIENT_CREDITS"
}Credits & Rate Limits
Credits
Each request consumes credits from your balance based on the depth parameter. If your balance is insufficient, the API returns HTTP 402. Failed requests are automatically refunded.
Rate Limits
Requests are subject to per-minute and per-day limits based on your plan. Exceeding limits returns HTTP 429.
Caching
Responses are cached for 24 hours. Repeated requests with the same keyword, language, country, and depth are served from cache at no additional credit cost.
