Image Search: Find Images with the Custom Search API

The Custom Search JSON API supports full image search through a single additional parameter: searchType=image. Add it to any standard request and the API returns image-specific results instead of web pages — each with dimensions, thumbnail URLs, byte sizes, and the hosting context. You can then layer on filters for image size, format, color profile, and dominant color to match exactly the kind of visual content your application needs.

How image search works

When you set searchType=image, Google’s index returns image results rather than web documents. Each result in the items[] array includes an image sub-object containing the full-resolution URL, its dimensions and file size, plus a thumbnailLink for lightweight preview rendering. The link field points to the direct image URL; displayLink and contextLink tell you the originating domain and page.

Your Programmable Search Engine must have Image search enabled. Open the Control Panel, select your engine, go to Search features → Image search, and toggle it on.

Key parameters

string

required

Set to image to switch the response to image results. Omitting this parameter returns standard web results.

string

required

Your image search query. Standard Google operators work here too — for example q=golden+retriever+puppy or q=logo+filetype:png.

string

Filter by image dimensions. Accepted values:

Value	Approximate size
`icon`	Up to 24 × 24 px
`small`	24 × 24 – 64 × 64 px
`medium`	64 × 64 – 128 × 128 px
`large`	128 × 128 – 256 × 256 px
`xlarge`	256 × 256 – 512 × 512 px
`xxlarge`	512 × 512 – 1024 × 1024 px
`huge`	Larger than 1024 × 1024 px

string

Filter by the kind of image content. Accepted values:

Value	Description
`clipart`	Clip-art style illustrations
`face`	Photos primarily featuring a human face
`lineart`	Black-and-white line drawings
`news`	Images from news stories
`photo`	Photographs (general)

string

Filter by the color profile of the image. Accepted values:

Value	Description
`color`	Full-color images
`gray`	Grayscale images
`mono`	Black-and-white (monochrome) images
`trans`	Images with a transparent background

string

Return only images where a single color dominates. Accepted values: black, blue, brown, gray, green, orange, pink, purple, red, teal, white, yellow.

integer

Number of image results per page. Accepts 1–10. Defaults to 10.

integer

1-based offset into the result set. Maximum 91. Use with num to paginate.

string

Safe-search level. active enables strict filtering; off disables it. Defaults to off.

Make your first image search request

Enable image search on your engine

Visit the Programmable Search Engine Control Panel, open your engine’s settings, and enable Image search under Search features.

Build the request

Add searchType=image alongside your existing key, cx, and q parameters. All other filters are optional:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&searchType=image\
&q=mountain+landscape"

Apply image-specific filters

Narrow results by size, type, and color in a single request:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&searchType=image\
&q=mountain+landscape\
&imgSize=xlarge\
&imgType=photo\
&imgColorType=color\
&imgDominantColor=blue"

Full curl example

The request below fetches large, full-color photos of red foxes in the wild with safe search on:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&searchType=image\
&q=red+fox+in+the+wild\
&imgSize=large\
&imgType=photo\
&imgColorType=color\
&imgDominantColor=red\
&safe=active\
&num=10"

Sample image result item

The items[] array in an image search response has the same top-level fields as a web search result, plus an image sub-object:

{
  "kind": "customsearch#result",
  "title": "Red Fox in Autumn Forest",
  "htmlTitle": "<b>Red Fox</b> in Autumn Forest",
  "link": "https://example-wildlife.com/images/red-fox-autumn.jpg",
  "displayLink": "example-wildlife.com",
  "snippet": "A red fox (Vulpes vulpes) photographed during autumn in a deciduous forest in northern Europe.",
  "htmlSnippet": "A <b>red fox</b> (<em>Vulpes vulpes</em>) photographed during autumn in a deciduous forest...",
  "mime": "image/jpeg",
  "fileFormat": "image/jpeg",
  "image": {
    "contextLink": "https://example-wildlife.com/gallery/foxes",
    "height": 1080,
    "width": 1920,
    "byteSize": 548432,
    "thumbnailLink": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR...",
    "thumbnailHeight": 101,
    "thumbnailWidth": 180
  }
}

Understand the `image` sub-object

string

URL of the web page that hosts the image. Use this to attribute the image source or link back to the originating page.

integer

Full-resolution height of the image in pixels.

integer

Full-resolution width of the image in pixels.

integer

File size of the full-resolution image in bytes.

string

URL of a Google-hosted thumbnail. Suitable for building image grids without hotlinking the original source.

integer

Height of the thumbnail image in pixels.

integer

Width of the thumbnail image in pixels.

Common patterns

Transparent PNG icons
High-resolution photos
Grayscale portraits

Fetch transparent-background icon images — useful for logo searches or UI asset discovery:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&searchType=image\
&q=cloud+storage+icon\
&imgType=clipart\
&imgColorType=trans\
&imgSize=medium"

Retrieve only large photographs suitable for editorial or print use:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&searchType=image\
&q=northern+lights+iceland\
&imgType=photo\
&imgSize=huge\
&imgColorType=color"

Find black-and-white portrait photographs:

curl "https://www.googleapis.com/customsearch/v1\
?key=YOUR_API_KEY\
&cx=YOUR_CX\
&searchType=image\
&q=portrait+photography\
&imgType=face\
&imgColorType=gray"

Display images responsibly

The link field points to a third-party image URL. Do not hotlink production traffic directly to these URLs — the source server may apply rate limits, move the file, or have terms of service that prohibit hotlinking. Fetch and cache the image on your own infrastructure, or use thumbnailLink for preview purposes.

Always attribute the image source using image.contextLink and respect the licensing terms of the originating site. For royalty-free or Creative Commons images, combine image search with the rights filter (see Advanced Filters).

Error reference

HTTP status	Meaning	Common cause
`400`	Bad request	Invalid `imgSize`, `imgType`, or `imgColorType` value
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	Quota exceeded, or image search not enabled on the engine
`429`	Too many requests	Rate limit exceeded; apply exponential back-off
`500`	Server error	Transient issue; retry with back-off

Enable SafeSearch (safe=active) whenever your application might serve minors or operates in a regulated context. The default (off) returns unfiltered results.

Get Started

Core Concepts

Search Features

Guides

Help

Image Search: Find Images with the Custom Search API

How image search works

Key parameters

Make your first image search request

Full curl example

Sample image result item

Understand the `image` sub-object

Common patterns

Display images responsibly

Error reference

​How image search works

​Key parameters

​Make your first image search request

​Full curl example

​Sample image result item

​Understand the image sub-object

​Common patterns

​Display images responsibly

​Error reference

How image search works

Key parameters

Make your first image search request

Full curl example

Sample image result item

Understand the `image` sub-object

Common patterns

Display images responsibly

Error reference