GET /customsearch/v1 Image Search Endpoint Reference

To search for images instead of web pages, send a standard request to the Custom Search JSON API and add searchType=image. The API returns image results with dimensions, thumbnail URLs, and hosting context — everything you need to build an image search experience. All the standard filtering parameters (q, num, start, safe, lr, gl, siteSearch) work alongside the image-specific parameters documented below.

Endpoint

GET https://www.googleapis.com/customsearch/v1

Request Parameters

Core Parameters (Required)

string

required

Your Google API key. Every request must include this parameter.

string

required

Your Programmable Search Engine ID. Image search must be enabled in the search engine settings at programmablesearchengine.google.com.

string

required

The image search query. Describe the visual content you want — for example "golden gate bridge sunset" or "python logo transparent".

string

required

Must be set to image to receive image results instead of web results. This is the only accepted value.

Pagination Parameters

integer

default:"10"

Number of image results to return. Accepted values are 1 through 10.

integer

default:"1"

Index of the first result. Use in combination with num to page through results. Maximum value is 91.

Image Filter Parameters

string

Restricts results to images of a specific size. Accepted values:

huge — Very large images.
icon — Icon-sized images.
large — Large images.
medium — Medium-sized images.
small — Small images.
xlarge — Extra-large images.
xxlarge — Extra-extra-large images.

string

Restricts results to images of a specific type. Accepted values:

clipart — Clip art images.
face — Images that contain faces.
lineart — Line drawings.
stock — Stock photography.
photo — Photographs.
animated — Animated GIFs.

string

Filters images by their color model. Accepted values:

color — Full-color images.
gray — Grayscale images.
mono — Black-and-white images (1-bit).
trans — Images with a transparent background.

string

Filters images by their dominant color. Accepted values:black, blue, brown, gray, green, orange, pink, purple, red, teal, white, yellow.

Safety and Region Parameters

string

default:"off"

SafeSearch filter. Pass active to filter explicit images, or off to disable filtering.

string

Restricts results to images hosted on pages written in a specific language. Example: lang_en.

string

Biases results toward a specific country. Accepts a two-letter ISO 3166-1 alpha-2 country code such as us or jp.

string

Limits image results to a specific domain or site, for example siteSearch=unsplash.com.

string

Filters results by Creative Commons license type. Accepted values include cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived, or combinations joined by |.

Example Request

The following request searches for large color photographs of mountain landscapes with SafeSearch enabled.

cURL

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_SEARCH_ENGINE_ID\
&q=mountain+landscape\
&searchType=image\
&imgSize=large\
&imgType=photo\
&imgColorType=color\
&safe=active\
&num=5"

import requests

params = {
    "key": "YOUR_API_KEY",
    "cx": "YOUR_SEARCH_ENGINE_ID",
    "q": "mountain landscape",
    "searchType": "image",
    "imgSize": "large",
    "imgType": "photo",
    "imgColorType": "color",
    "safe": "active",
    "num": 5,
}

response = requests.get(
    "https://www.googleapis.com/customsearch/v1",
    params=params
)
data = response.json()

for item in data.get("items", []):
    img = item.get("image", {})
    print(item["title"])
    print(f"  Full image:  {item['link']}")
    print(f"  Thumbnail:   {img.get('thumbnailLink')}")
    print(f"  Dimensions:  {img.get('width')}x{img.get('height')}")

const params = new URLSearchParams({
  key: "YOUR_API_KEY",
  cx: "YOUR_SEARCH_ENGINE_ID",
  q: "mountain landscape",
  searchType: "image",
  imgSize: "large",
  imgType: "photo",
  imgColorType: "color",
  safe: "active",
  num: "5",
});

const response = await fetch(
  `https://www.googleapis.com/customsearch/v1?${params}`
);
const data = await response.json();

for (const item of data.items ?? []) {
  const img = item.image ?? {};
  console.log(item.title);
  console.log(`  Full image:  ${item.link}`);
  console.log(`  Thumbnail:   ${img.thumbnailLink}`);
  console.log(`  Dimensions:  ${img.width}x${img.height}`);
}

Example Response

{
  "kind": "customsearch#search",
  "searchInformation": {
    "searchTime": 0.318742,
    "totalResults": "2150000000"
  },
  "items": [
    {
      "kind": "customsearch#result",
      "title": "Breathtaking Mountain Landscape at Golden Hour",
      "htmlTitle": "Breathtaking <b>Mountain Landscape</b> at Golden Hour",
      "link": "https://www.example-photos.com/images/mountain-golden-hour.jpg",
      "displayLink": "www.example-photos.com",
      "snippet": "A sweeping panoramic view of alpine peaks lit by golden-hour sunlight.",
      "htmlSnippet": "A sweeping panoramic view of alpine peaks lit by golden-hour sunlight.",
      "mime": "image/jpeg",
      "fileFormat": "image/jpeg",
      "image": {
        "contextLink": "https://www.example-photos.com/gallery/mountain-golden-hour",
        "height": 3000,
        "width": 4500,
        "byteSize": 4823201,
        "thumbnailLink": "https://encrypted-tbn0.gstatic.com/images?q=tbn:abc123",
        "thumbnailHeight": 150,
        "thumbnailWidth": 225
      }
    }
  ]
}

Response Fields

Image results share the same top-level structure as web results (kind, searchInformation, queries, items). The key difference is the image sub-object present on every result item.

string

Plain-text title of the page that hosts the image.

string

Direct URL of the full-resolution image file.

string

Human-readable hostname of the page hosting the image, e.g. "www.example-photos.com".

string

A short text excerpt from the surrounding page content describing the image.

string

MIME type of the image file, e.g. "image/jpeg", "image/png", or "image/gif".

object

An object containing image-specific metadata.

Show image fields

string

URL of the web page where this image appears. Use this to link users back to the source page rather than the raw image file.

integer

Height of the full-resolution image in pixels.

integer

Width of the full-resolution image in pixels.

integer

File size of the full-resolution image in bytes.

string

URL of a Google-hosted thumbnail version of the image. Use this for previews in your UI to avoid loading full-resolution files.

integer

Height of the thumbnail image in pixels.

integer

Width of the thumbnail image in pixels.

Error Codes

HTTP Status	Meaning
`400`	Bad request — `searchType` value is invalid or a required parameter is missing.
`401`	Invalid API key.
`403`	Quota exceeded, or image search is not enabled on the specified search engine.
`429`	Too many requests — apply exponential backoff and retry.
`500`	Internal server error — retry after a short delay.

Image search must be explicitly enabled on your Programmable Search Engine. Log in to programmablesearchengine.google.com, open your engine, navigate to Search features → Image search, and toggle it on. Requests with searchType=image against an engine without this setting return a 403 error.

Always link to image.contextLink rather than items[].link (the raw image URL) in your UI. Displaying the source page respects copyright attribution and provides a better user experience.

​Endpoint

​Request Parameters

​Core Parameters (Required)

​Pagination Parameters

​Image Filter Parameters

​Safety and Region Parameters

​Example Request

​Example Response

​Response Fields

​Error Codes

Endpoint

Request Parameters

Core Parameters (Required)

Pagination Parameters

Image Filter Parameters

Safety and Region Parameters

Example Request

Example Response

Response Fields

Error Codes