Image search
search_imagesSearch for images using Google Programmable Search Engine with filters like size, type, color, license, language, country, date, and site. Returns direct image URLs, dimensions, and thumbnails.
Instructions
Image search through your Google Programmable Search Engine (searchType=image). Works only when the engine has "Image search" enabled in its control panel — otherwise the API answers 400. Each item's url is the image file itself; image.context_url is the page hosting it, with width/height/byte_size and a thumbnail_url (plus its dimensions) for previews. Everything else matches the search tool: same filters (language/country, safe search, site include/exclude, date_restrict, file_type, rights — use rights for reusable images), same pagination (max 10 per call, 100 per query, paginate via next_start), same quota (one unit per call). Image-only filters: size (icon..huge), type (clipart/face/lineart/stock/photo/animated), color_type (mono/gray/color/trans) and dominant_color.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| num | No | Results per page, 1..10 (API maximum 10; default 10). | |
| safe | No | Safe search: active filters adult content, off (the API default) does not. | |
| size | No | Image size class, from icon to huge. | |
| sort | No | Sort expression, e.g. "date" for newest-first. Omit for relevance (usually better). | |
| type | No | Kind of image. | |
| query | Yes | The search query, Google syntax included (quotes, site:, filetype:, OR, -exclusions). | |
| start | No | 1-based index of the first result — use next_start/previous_start from the previous page. The API serves at most 100 results per query, so start + num - 1 must stay <= 100 (enforced: a wider window is rejected without spending quota). | |
| rights | No | License filter: cc_publicdomain, cc_attribute, cc_sharealike, cc_noncommercial, cc_nonderived (combine with |). | |
| country | No | Geolocation bias — rank results as if searching from this country, e.g. "de". Soft signal. | |
| language | No | Only results in this language, e.g. "en", "de", "zh-CN". | |
| or_terms | No | Space-separated words — each result must contain at least one of them. | |
| engine_id | No | Programmable Search Engine id (cx) to search with, overriding the configured GOOGLE_CUSTOM_SEARCH_ENGINE_ID. Omit to use the configured engine. | |
| file_type | No | Only files of this type, e.g. "pdf", "xlsx", "svg". | |
| color_type | No | mono = black & white, trans = transparent background. | |
| exact_terms | No | A phrase every result must contain. | |
| site_search | No | A site or domain to include or exclude, e.g. "example.com" — pair with site_search_filter. | |
| date_restrict | No | Only results from the last N days/weeks/months/years: "d7", "w2", "m6", "y1", ... | |
| exclude_terms | No | A word or phrase no result may contain. | |
| dominant_color | No | Prefer images dominated by this color. | |
| include_pagemap | No | Attach each result's raw pagemap (OpenGraph/metatags/thumbnails and other structured page data). Verbose — leave off unless you need page metadata. | |
| country_restrict | No | Hard filter — only documents Google attributes to this country, e.g. "DE". | |
| filter_duplicates | No | Google's duplicate-content filter (default on). false returns near-duplicate results too. | |
| interface_language | No | Interface language used to interpret the query, e.g. "de". Improves non-English relevance. | |
| site_search_filter | No | include = only results from site_search, exclude = everything but it. Default include. |