semust logo

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.

HeaderTypeDescription
SEMUST-API-USERstringYour API user's username
SEMUST-API-PASSWORDstringYour API user's password

Create API credentials from the API Access page.

SEMUST-API-USER: your_username
SEMUST-API-PASSWORD: your_password

Request Parameters

Send a application/json body with the following parameters:

Body

keywordstringrequired

The search query for Google Images (e.g., "istanbul manzara", "modern architecture").

languagestringdefault: en

Language code (ISO 639-1). Controls the language of search results. Examples: "en", "tr", "de", "fr", "es".

countrystringdefault: US

Country code (ISO 3166-1 alpha-2). Geo-targets image results to a specific country. Examples: "US", "TR", "DE", "GB".

depthintegerdefault: 100

Number 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
  }'

Response

Returns a JSON object with image results and related search suggestions.

Response Fields

FieldTypeDescription
successbooleanAlways true on successful response
result_countintegerNumber of images returned
keywordstringThe search keyword used
countrystringThe country used for search
languagestringThe language used for search
imagesarrayArray of image result objects
related_searchesarrayRelated search suggestions (may be empty)

Image Object Fields

FieldTypeDescription
positionintegerPosition/rank of the image in results (1-indexed)
titlestringTitle or name of the image
subtitlestringAdditional subtitle or description
altstringAlt text for the image
urlstringDirect URL to the image file
source_urlstringURL of the webpage containing the image
FieldTypeDescription
titlestringSuggested related search term
urlstringURL 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.

HTTPCodeMeaning
400INVALID_REQUESTRequest body is malformed or missing required fields
400KEYWORD_REQUIREDThe keyword field is empty or missing
401INVALID_API_KEYAuthentication failed — invalid username or password
402INSUFFICIENT_CREDITSYour account does not have enough credits
200EMPTY_RESULTSNo image results found for this query
500INTERNAL_ERRORAn internal server error occurred
502WORKER_FAILEDFailed to fetch Google Images results from the worker
504TIMEOUTThe 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.

Last updated: 2026-08-22