Yahoo Image Search API documentation for developers who need Yahoo image results as JSON. Scrappa's GET /api/yahoo/images endpoint returns about 60 images per page with the original image, the page it sits on, a thumbnail, width, height and domain.
How to call the endpoint
Send a GET request with a required q and your API key in the x-api-key header. Page with page (1-10). Narrow the set with size, color, type, layout, age, format and license. Each value returns a different set of images. With layout, images that do not match the shape are removed. Neighbouring pages can repeat a few images, so de-duplicate by image_url when you merge pages. A page without images is not billed.
Response fields
Each image has position, title, image_url, source_url, thumbnail, width, height and domain. has_more tells you if another page is likely.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
1 required parameter needed before sending a request.
8 optional filters available.
string
Required
Image search query (max 500 characters).
Example: cats
coffee shops
integer
Optional
Page number, about 60 images per page.
Range: 1-10
Default: 1
1
string
Optional
Image size: small, medium, large or wallpaper (extra large).
example
string
Optional
color, bw, red, orange, yellow, green, teal, blue, purple, pink, brown, black, gray or white.
example
string
Optional
Image type: photo, clipart, linedrawing, gif (animated) or transparent.
example
string
Optional
Image shape: square, wide or tall.
example
string
Optional
Only images up to this age: day, week, month or year.
example
string
Optional
People in the image: face (faces only), portrait (head and shoulders) or no_people.
example
string
Optional
Usage rights: creative_commons, public_domain, share, share_commercial, modify or modify_commercial.
example
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
page
query
source
filters
has_more
results_on_page
Common data fields
title
width
domain
height
{
"data": [
{
"title": "14 Cute Cat Breeds Anyone Will Love",
"width": 3684,
"domain": "www.thesprucepets.com",
"height": 2456,
"position": 1,
"image_url": "https://www.thesprucepets.com/thmb/_Wn1KhNomGgBw_9Ck-ESlyP2v4Q=/3684x2456/filters:no_upscale():max_bytes(150000):strip_icc()/GettyImages-1168381542-eb602851e1de49f399601414a80acf8f.jpg",
"thumbnail": "https://tse4.mm.bing.net/th/id/OIP.xshLoNgET_H1sUjZ5o7ahQHaE8?r=0&pid=Api&h=220&P=0",
"source_url": "https://www.thesprucepets.com/cute-cat-breeds-5176271"
}
],
"page": 1,
"query": "cats",
"source": "yahoo",
"filters": [],
"has_more": true,
"results_on_page": 1
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
The q parameter is missing, or page, size, color, type, layout, age, format or license failed validation.
{
"errors": {
"q": [
"The q parameter (search query) is required."
]
},
"message": "The request validation failed"
}Yahoo Temporarily Unavailable
Yahoo did not return usable data after the bounded retry on a second route. The request is not billed. Retry shortly.
{
"error": "Yahoo is temporarily unavailable. Please retry shortly.",
"retryable": true,
"error_code": "yahoo_upstream_unavailable"
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.