Image search (/images)

Reference for /images: image search parameters, response fields, code in 5 languages, GET and POST forms, and a sample response.

Updated View as Markdown

Google Images results with full-size image URLs and dimensions. Results are in images. The product page is Google Images API.

Try in PlaygroundOpens the dashboard playground with this request filled in (sign in first).

Request

POST https://api.bestserp.com/images with a JSON body, or GET https://api.bestserp.com/images with the same parameters in the query string. The key goes in the X-API-KEY header either way (authentication).

POST
curl -X POST 'https://api.bestserp.com/images' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"q":"golden retriever"}'
GET
curl -G 'https://api.bestserp.com/images' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  --data-urlencode 'q=golden retriever'

Parameters

Unknown parameters are refused (unknown_parameter), so a typo never goes unnoticed.

ParameterTypeDefaultDescription
qrequiredstringSearch query (1–256 characters).
glstringusCountry, 2-letter code (us, gb, vn, de…). The search runs from an IP in that country when one is free, else from another one (see ipCountry).
hlstringenInterface language (en, vi, de…).
pagesinteger1Result pages or scroll loads to fetch, 1–5. Each costs 1 credit.
tbsstringRecency: qdr:h (hour), qdr:d (day), qdr:w (week), qdr:m (month), qdr:y (year). Also accepted: timeRange = hour|day|week|month|year.
noCachebooleanfalseSkip the 1-hour result cache (5 minutes for news).
asyncbooleanfalseAnswer 202 immediately with a requestId to poll.
timeoutnumber60Seconds to wait before answering 202 (1–120).
autocorrectbooleanAccepted for compatibility; no effect.

Response fields

Empty fields are left out of each item.

images[]

FieldMeaning
positionRank of the image, from 1.
titleTitle of the image or its page.
imageUrlURL of the full-size image.
imageWidthWidth of the full-size image, in pixels.
imageHeightHeight of the full-size image, in pixels.
thumbnailUrlGoogle's thumbnail of the image.
sourceSite name of the page that hosts the image.
domainHost name of that page, without www.
linkURL of the page that hosts the image.

Every response

FieldMeaning
searchParametersYour request after validation, with defaults filled in (q, gl, hl, type, page or pages...).
requestIdID of this request. Poll GET /requests/{requestId} for async requests and for final links.
creditsCredits charged for this request (refunded automatically if it fails).
cachedtrue when the answer came from the recent-result cache (1 hour, 5 minutes for news).
linksPendingtrue while Google redirect links are being replaced by final URLs; poll the request to get them.
unresolvedLinksLinks that are still Google redirects: they work, but are not the final URL.
durationMsTime the search took, in milliseconds.
ipCountryCountry of the IP the search ran from (same code as gl). Another country than gl when no IP there was free: the search runs anyway instead of waiting. Missing when unknown.

Sample response

200 OK
{
  "searchParameters": {
    "q": "golden retriever",
    "gl": "us",
    "hl": "en",
    "type": "images",
    "pages": 1,
    "engine": "google"
  },
  "images": [
    {
      "position": 1,
      "title": "Golden retriever puppy in the grass",
      "imageUrl": "https://pupphotos.com/images/golden-puppy.jpg",
      "imageWidth": 1600,
      "imageHeight": 1067,
      "thumbnailUrl": "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='320' height='200'><rect width='320' height='200' fill='%23f5c26b'/></svg>",
      "source": "Pup Photos",
      "domain": "pupphotos.com",
      "link": "https://pupphotos.com/golden-puppy"
    },
    {
      "position": 2,
      "title": "Golden Retriever: breed characteristics and care",
      "imageUrl": "https://dogbreedguide.com/images/golden-breed.jpg",
      "imageWidth": 1200,
      "imageHeight": 800,
      "thumbnailUrl": "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='320' height='200'><rect width='320' height='200' fill='%23e9b35a'/></svg>",
      "source": "Dog Breed Guide",
      "domain": "dogbreedguide.com",
      "link": "https://dogbreedguide.com/golden-breed"
    },
    {
      "position": 3,
      "title": "Golden retriever running on the beach",
      "imageUrl": "https://happytails.blog/images/golden-beach.jpg",
      "imageWidth": 1920,
      "imageHeight": 1280,
      "thumbnailUrl": "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='320' height='200'><rect width='320' height='200' fill='%23f7d9a0'/></svg>",
      "source": "Happy Tails",
      "domain": "happytails.blog",
      "link": "https://happytails.blog/golden-beach"
    },
    {
      "position": 4,
      "title": "Two golden retrievers playing",
      "imageUrl": "https://petdaily.com/images/golden-two.jpg",
      "imageWidth": 1080,
      "imageHeight": 1080,
      "thumbnailUrl": "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='320' height='200'><rect width='320' height='200' fill='%23f0c47a'/></svg>",
      "source": "Pet Daily",
      "domain": "petdaily.com",
      "link": "https://petdaily.com/golden-two"
    }
  ],
  "requestId": "5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11",
  "credits": 1,
  "cached": false,
  "linksPending": false,
  "unresolvedLinks": 0,
  "durationMs": 2410
}

Limits

  • Image search filters (size, color, type, usage rights) are not supported yet; only the recency filter (tbs) is.
  • Up to 5 scroll loads (pages) per request; each costs 1 credit.
  • Targeting is by country (gl) and interface language (hl). City-level location is not supported yet: a request with location is refused with an explicit error.
  • Results are what a desktop browser sees. There is no mobile SERP option yet.
  • 60 searches per minute per account by default; ask on Telegram for more.

Errors and their credit rules are on the errors page.