Images
Search the image index itself and get picture URLs. 1 credit per block of 10 results — see Credits.
This is not search(include_images: true).
That runs a web search and returns the hero image each article happened to
use, so a query for blue birds matches Blue Bird Corporation and hands back
stock-ticker articles whose images are site logos. This endpoint ranks the image
index, so it returns pictures of the subject.
Use include_images when you want an illustration for a page
you are already citing. Use this when you want a picture.
Parameters#
| Field | Type | Description |
|---|---|---|
queryrequired | string | What the picture should show, e.g. blue jay in snow. 1–400 characters. |
countopt | int | Number of images, up to 50. Default 10. Rounded up to a block of 10, because that is the unit you are billed. |
max_syndicationopt | int | Cap on how many distinct pages an image may appear on, 1–1000. Default 30. This is the stock-photography filter: an image reused across thousands of articles is site furniture, not a picture of your subject. Lower it for something distinctive, raise it for a widely-published news photo. |
Request#
Response#
Result fields#
| Field | Type | Description |
|---|---|---|
url | string | The image itself. This is what you render or download. |
caption | string | Show this to a person. The alt text when it is usable, and the page title when it is not. |
title | string | The raw alt attribute, exactly as published. Unusable on roughly a quarter of images — empty, or filename-derived like pn/fa b b dd deb. Kept because it is the most accurate description when it is present; prefer caption for display. |
width · height | int | Pixel dimensions. null when the source did not declare them, which is common — do not filter on these being present. |
page_url · page_title | string | The page the image was found on. Cite this, not the image URL, when attributing. |
domain | string | Host serving the image. |
is_hero | bool | True when it was the page's lead image rather than an inline one. |
seen_on_pages | int | How many distinct pages carry this image. High numbers mean stock art; max_syndication filters on it. |
Counting results#
The index stops counting at 10,000. When it does, total is
10000 and total_is_lower_bound is
true — meaning “at least this many”, not “this many”. Check the
flag before presenting total as an exact figure.
Working with results#
- Never construct an image URL. Use only URLs the API returned. A URL guessed from a subject name or a page address does not exist, and the reader gets a broken image instead of a picture.
- Do not require a meaningful
title. Alt text is missing or junk on about a quarter of images, and some of the best photographs have the worst captions. Judge a result byurl,captionand dimensions. - Hotlinking is the caller's call. These are third-party URLs on their original hosts. Some sites block cross-origin image requests; if you are displaying images to end users, expect a small share to fail and handle it.
- Coverage is narrower than web search. The image index is smaller than the page index, so a phrase that finds articles may find few pictures. Try the subject alone before concluding there is nothing.