Google Images

Search Google Images to retrieve image results in JSON format.

Endpoint

GET /v1/image/{query}

Description

The Google Images Search endpoint returns image results for a query, each with a thumbnail set, the page the image was found on, and the original image's URL and dimensions.

Results arrive in the image_results array. The results array that the other search endpoints populate is always empty here — see Response below.

Authentication

All requests require authentication using the X-Api-Key header. See the Authentication guide for more details.

Path Parameters

query (required)

Type: string

The search terms, packed into the path. Both the q=-prefixed form and a bare term are accepted and return the same results:

Examples:

  • q=vintage+bicycle
  • vintage+bicycle

Unlike Google Search, this endpoint takes only the search terms. Every call returns up to 20 images, and there is no pagination parameter.

Prefer the q= form if you pass anything else. Additional Google parameters are dropped only when the path is a query string this endpoint can parse, which means it needs the q= key: q=origami+crane&num=5 searches for origami crane and ignores num. Appended to a bare term, the same parameter becomes part of the search — origami+crane&num=5 looks for the literal text origami crane&num=5 and returns unrelated images rather than an error.

Request Headers

X-Proxy-Location (optional)

Type: string

Specify the proxy location for the search. This determines the geographic location from which the search is performed.

Allowed values:

  • EU - European Union
  • CA - Canada
  • US - United States
  • IE - Ireland
  • GB - United Kingdom
  • FR - France
  • DE - Germany
  • SE - Sweden
  • IN - India
  • JP - Japan
  • KR - South Korea
  • SG - Singapore
  • AU - Australia
  • BR - Brazil

X-User-Agent (optional)

Type: string

Specify the device type for the search. Defaults to desktop if not provided.

Allowed values:

  • desktop - Desktop browser (default)
  • mobile - Mobile device

Request Example

Using cURL

curl --request GET \
  --url 'https://api.serply.io/v1/image/q=vintage+bicycle' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'X-Proxy-Location: US' \
  --header 'X-User-Agent: desktop'

Using JavaScript/Node.js

const response = await fetch('https://api.serply.io/v1/image/q=vintage+bicycle', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Proxy-Location': 'US',
    'X-User-Agent': 'desktop'
  }
});
const data = await response.json();
console.log(data.image_results);

Using Python

import requests

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Proxy-Location': 'US',
    'X-User-Agent': 'desktop'
}

response = requests.get(
    'https://api.serply.io/v1/image/q=vintage+bicycle',
    headers=headers
)
data = response.json()
print(data['image_results'])

Response

The API returns a JSON object whose image_results array carries the images. The other SERP-feature arrays are present for consistency with the rest of the API and are empty on this endpoint.

Response Structure

{
  "image_results": [
    {
      "image": {
        "src": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSpyW8...&s",
        "alt": "Ladies Classic 7-Speed Vintage Bike Red - Reid Bikes"
      },
      "link": {
        "href": "https://shop.reidbikes.com/products/ladies-classic-7-speed-vintage-bike-red",
        "title": "Ladies Classic 7-Speed Vintage Bike Red - Reid Bikes",
        "domain": "shop.reidbikes.com"
      },
      "original_image": {
        "src": "http://shop.reidbikes.com/cdn/shop/files/ladies-classic-vintage-bike-red.png",
        "width": "1170",
        "height": "764",
        "file_format": "image/png"
      },
      "thumbnails": {
        "small": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSpyW8...&s",
        "medium": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRn7d-...&s",
        "large": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQZilx...&s"
      }
    }
  ],
  "results": [],
  "ads": [],
  "ads_count": 0,
  "answers": [],
  "shopping_ads": [],
  "places": [],
  "related_searches": [],
  "carousel": [],
  "company": {},
  "total": 20,
  "ts": 1.27,
  "device_region": "",
  "device_type": null,
  "query": "q=vintage+bicycle"
}

Response Fields

  • image_results (array): An array of image result objects
    • image (object): The result as shown on the results page
      • src (string): Thumbnail URL, served from Google's encrypted-tbn0.gstatic.com cache rather than the source site
      • alt (string): Alt text, generally the source page's title
    • link (object): Where the image was found
      • href (string): URL of the page hosting the image
      • title (string): Title of that page
      • domain (string): Hostname of that page
    • original_image (object): The full-size image on the source site
      • src (string): Direct URL to the original image. Served by the source site, so it may be http://, may be hotlink-protected, and may 404 independently of the search result
      • width, height (string): Pixel dimensions of the original, as strings
      • file_format (string): MIME type, e.g. image/jpeg, image/png, image/webp, image/svg+xml. Google does not always report the subtype, in which case this is the bare string image/ — treat it as unknown rather than parsing it, and fall back to the extension on src if you need the real format
    • thumbnails (object): Three cached preview sizes — small, medium, large (strings). All are Google-hosted and safe to hotlink
  • results (array): Always empty on this endpoint. Image results are in image_results
  • total (number): Number of images returned, up to 20
  • ts (number): Time in seconds the request took to complete
  • device_region (string): Proxy region used, if specified via X-Proxy-Location
  • device_type (string | null): Device type used for the search
  • query (string): The path segment as sent, echoed verbatim — so a request for q=vintage+bicycle reports "q=vintage+bicycle", not "vintage bicycle"
  • ads, answers, shopping_ads, places, related_searches, carousel (arrays), company (object), ads_count (number): Present for consistency with the other search endpoints; empty here

Status Codes

  • 200 OK - Successful response
  • 404 Not Found - The requested resource was not found
  • 422 Unprocessable Entity - The request was well-formed but contains semantic errors
  • 429 Too Many Requests - Rate limit exceeded

Error Responses

See the Errors guide for information on error response formats.

View as Markdown