POST /images

Google Images API

The BestSERP Google Images API runs a live Google Images search and returns each image as JSON: the full-size image URL, its width and height, Google's thumbnail, the title, and the page and site that host it. Ask for up to 5 scroll loads per request, at one credit each.

Last updated:

Key takeaways

  • /images returns images with title, imageUrl, imageWidth, imageHeight, thumbnailUrl and more.
  • Target any country with gl and any language with hl; city-level location is not supported yet.
  • 1 credit per page of results ($0.50 per 1,000 after 3,000 free); failed searches are refunded.
  • POST a JSON body or GET with the same parameters; the key goes in the X-API-KEY header.

Try the Google Images API

Pick a suggested query to see a saved response, or type your own for a live search (3 free per day).

Loading the live demo

Send a request

POST a JSON body to https://api.bestserp.com/images with your key in the X-API-KEY header. Replace YOUR_API_KEY and run.
curl -X POST 'https://api.bestserp.com/images' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"q":"golden retriever"}'

Parameters

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

Results are in images. Empty fields are left out.

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

A trimmed response for "golden retriever". Your results reflect Google at the time of the request.
{
  "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
}

What you can build

  • Visual research

    Collect reference images for a topic or product, with the page each one comes from.

  • Brand and image monitoring

    See which sites show your product photos or logo for a query.

  • SEO tools

    Check how a site's images rank in Google Images for target keywords.

    SEO tools guide

Current limits

What this API does not do yet, so you can decide before you build on it.
  • 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.

Pricing: 1 credit per page of results, 3,000 free credits, then $0.50 per 1,000. See pricing

Frequently asked questions

Do I get the full-size image or only a thumbnail?
Both: imageUrl is the full-size image and thumbnailUrl is Google's thumbnail, with imageWidth and imageHeight of the full image.
How many images does a request return?
The images Google loads for one scroll of the results. Set pages up to 5 to load more; each load costs 1 credit.
Can I filter by image size or color?
Not yet. You can limit results by recency with tbs (qdr:d, qdr:w, qdr:m...).
Can I use the images I find?
The API tells you where images are published; it does not grant any rights to them. Check the license on the source page before reusing an image.

Start with 3,000 free searches

No credit card. Sign in with Google, create a key, send your first request.