google-images-api

Google Images API

Google Images as JSON. Every tile comes back with the full-size file on the publisher's own server, its real pixel dimensions, and the page behind it, so you can filter and fetch without opening a browser.

Endpoint

One credit per request. A page carries about 100 images, which is the whole grid Google renders before it asks for another scroll.

GET/v1/images

bash

curl "https://api.serpix.io/v1/images?q=spiral+staircase&hl=en" \
  -H "Authorization: Bearer $SERPIX_API_KEY"

The same parameters are accepted as a JSON body on POST /v1/images:

post variant

curl -X POST "https://api.serpix.io/v1/images" \
  -H "Authorization: Bearer $SERPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "spiral staircase", "hl": "en"}'

Parameters

Query and localization
field	type	default	description
qrequired	string	–	The search query.
gl	string	–	Country to search from, two-letter code. Defaults to `us`.
hl	string	en	Language of the results page, two-letter code.

Results

Results
field	type	default	description
device	desktop \| mobile \| tablet	desktop	Results as Google serves them to a desktop browser or a phone.
page	integer	1	1-based page. Each page is a fresh set of about 100 images; pages do not overlap. One credit per page.
autocorrect	boolean	true	Set `false` to search the query exactly as typed, excluding results Google returns for its spell-corrected guess.
safe	active \| off	off	SafeSearch. `active` filters explicit results.

Image filters

Image filters
field	type	default	description
image_size	large \| medium \| icon	–	Coarse size bucket. Sets the same Google filter as `min_megapixels`, so send one or the other.
min_megapixels	2 \| 4 \| 6 \| 8 \| 10 \| 12 \| 15 \| 20 \| 40 \| 70	–	Only images larger than this. Google's own ladder, so the accepted values are the rungs it offers rather than any number.
image_color	transparent \| black_and_white \| red \| orange \| yellow \| green \| teal \| blue \| purple \| pink \| white \| gray \| black \| brown	–	A dominant colour, or `transparent` for images with an alpha channel, or `black_and_white`.
image_type	face \| photo \| clipart \| lineart \| animated	–	Kind of image: photograph, clip art, line drawing, animation, or face.

Rejected parameters

Unknown parameters are never silently ignored. A request carrying one is rejected with 422 before any search runs, so a typo can't bill you for results you didn't ask for. Common parameters from raw Google URLs and other SERP APIs get a pointed message naming the equivalent here:

Rejected aliases
field	type	default	description
num	422	–	Google serves a fixed grid of about 100 images. Paginate with `page`.
start	422	–	Use `page`, a 1-based page number, instead of a result offset.
ijn	422	–	Use `page`, which counts from 1 rather than 0.
tbs	422	–	Use the named filters: `image_size`, `min_megapixels`, `image_color`, `image_type`.
imgsz	422	–	Use `image_size` for the coarse bucket, or `min_megapixels` for a floor.
imgar / aspect_ratio	422	–	Google ignores the aspect-ratio filter on this vertical: the results come back identical to unfiltered.
licenses / usage_rights	422	–	Google ignores the usage-rights filter on this vertical, the same way.
nfpr	422	–	Use `autocorrect`.
chips	422	–	Not supported. Send a query from `suggested_searches` or `related_searches` back as `q`.
location / uule	422	–	Use `gl` and `hl`. City-level geotargeting is not wired for this vertical.
cr / lr	422	–	Not supported on this vertical.
udm / tbm	422	–	Not needed. This endpoint is the images vertical.
engine	422	–	Not needed. This endpoint is Google Images.
api_key	422	–	Authenticate with the `Authorization` header, never the query string.

422 · rejected parameter

HTTP/2 422
content-type: application/json

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["query"],
      "msg": "Value error, `ijn` is not supported: use `page` (1-based)",
      "input": { "q": "spiral staircase", "ijn": "2", ... }
    }
  ]
}

Response

A search returns one JSON object: two envelope objects that are always present (search_metadata, search_parameters), the grid as image_results, and the refinements Google served around it. A field that wasn't served is omitted entirely, never null, never [], so a presence check is all you need before reading one.

200 · trimmed

{
  "search_metadata": {
    "id": "srx_vSWO4uhMCJ2aO3VX",
    "status": "success",
    "created_at": "2026-07-28T17:46:30Z",
    "took_ms": 1414,
    "parser_version": "2026.07.1",
    "google_url": "https://www.google.com/search?q=spiral+staircase&udm=2&hl=en&gl=us&...",
    "html_url": "https://api.serpix.io/searches/srx_vSWO4uhMCJ2aO3VX/SqrmaiqqH445NtUC.html",
    "json_url": "https://api.serpix.io/searches/srx_vSWO4uhMCJ2aO3VX/SqrmaiqqH445NtUC.json"
  },
  "search_parameters": {
    "q": "spiral staircase",
    "gl": "us",
    "hl": "en",
    "device": "desktop",
    "page": 1
  },
  "image_results": [
    {
      "position": 1,
      "title": "Metal Spiral Staircases (Custom & Prefab) | Paragon Stairs",
      "link": "https://www.paragonstairs.com/spiral-stairs/materials/metal/?srsltid=AfmBOorK8xA...",
      "source": "Paragon Stairs",
      "original": "https://aws.paragonstairs.com/wp-content/uploads/2017/06/07135126/the-retreat.webp",
      "original_width": 554,
      "original_height": 554,
      "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSuVbCVywwV7wMPas...",
      "about_image_link": "https://www.google.com/search/about-this-image?img=H4sIAAAAAAAA_wEXAOj_...",
      "viewer_link": "https://www.google.com/imgres?imgurl=https%3A%2F%2Faws.paragonstairs.com%2Fwp-content%2F..."
    },
    ...
  ],
  "suggested_searches": [
    "metal spiral staircase",
    "modern spiral staircase",
    ...
  ],
  "related_searches": [
    "small spiral staircase",
    "outdoor spiral staircase",
    ...
  ],
  "pagination": {
    "current": 1,
    "next": "https://www.google.com/search?q=spiral+staircase&udm=2&hl=en&gl=us&start=10&..."
  }
}

Every response also reports its cost in the X-Serpix-Credits-Charged and X-Serpix-Credits-Remaining headers.

The grid

Each tile becomes one entry of image_results. The capture below is the grid exactly as Google served it, above the JSON it parsed into:

The gridHover or tap a tile to pair it with its entry

Google Images results for spiral staircase: a masonry grid of photographs, each captioned with a page title and publisher. — q=spiral staircase · desktop · google.com

image_results

[  {
    "position": 1,
    "title": "Metal Spiral Staircases (Custom & Prefab) | Paragon Stairs",
    "link": "https://www.paragonstairs.com/spiral-stairs/materials/metal/?srsltid=AfmBOoqYw...",
    "source": "Paragon Stairs",
    "original": "https://aws.paragonstairs.com/wp-content/uploads/2017/06/07135126/the-retreat....",
    "original_width": 554,
    "original_height": 554,
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSuVb...",
    "about_image_link": "https://www.google.com/search/about-this-image?img=H4sIAAA...",
    "viewer_link": "https://www.google.com/imgres?imgurl=https%3A%2F%2Faws.paragonstairs.com%2Fwp-content%2Fuploads%..."
  },  {
    "position": 2,
    "title": "Compact Spiral Stairs for Small Spaces",
    "link": "https://oakvalleydesigns.com/blogs/types-of-stairs/compact-spiral-stairs-for-s...",
    "source": "Oak Valley Designs",
    "original": "http://oakvalleydesigns.com/cdn/shop/articles/B0821_Compact_spiral_stairs_for_...",
    "original_width": 940,
    "original_height": 788,
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQi9z...",
    "about_image_link": "https://www.google.com/search/about-this-image?img=H4sIAAA...",
    "viewer_link": "https://www.google.com/imgres?imgurl=http%3A%2F%2Foakvalleydesigns.com%2Fcdn%2Fshop%2Farticles%2..."
  },  {
    "position": 3,
    "title": "Spiral Staircases for Home Innovations - DOLLE Montreal & Calgary",
    "link": "https://www.dolle.com/staircases/spiral-staircases",
    "source": "dolle",
    "original": "https://www.dolle.com/media/wysiwyg/Montreal-Classic-4-grey-140cm.jpg",
    "original_width": 800,
    "original_height": 500,
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQGdf...",
    "about_image_link": "https://www.google.com/search/about-this-image?img=H4sIAAA...",
    "viewer_link": "https://www.google.com/imgres?imgurl=https%3A%2F%2Fwww.dolle.com%2Fmedia%2Fwysiwyg%2FMontreal-Cl..."
  },  {
    "position": 4,
    "title": "Technical information Eurostair spiral staircase standard - Eurostair",
    "link": "https://www.eurostair.com/spiral-staircases/standard/technical-information/",
    "source": "Eurostair",
    "original": "https://www.datocms-assets.com/19065/1590750164-tecnical-image-spiral-standard...",
    "original_width": 750,
    "original_height": 1200,
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSiC2...",
    "about_image_link": "https://www.google.com/search/about-this-image?img=H4sIAAA...",
    "viewer_link": "https://www.google.com/imgres?imgurl=https%3A%2F%2Fwww.datocms-assets.com%2F19065%2F1590750164-t..."
  },  {
    "position": 5,
    "title": "Spiral Stairs – Space-Saving & Elegant Staircase Designs",
    "link": "https://southernstaircase.com/spiral-stairs/",
    "source": "Southern Staircase",
    "original": "https://southernstaircase.com/wp-content/uploads/2023/04/Black-Residence-Spira...",
    "original_width": 1707,
    "original_height": 2560,
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR4BJ...",
    "about_image_link": "https://www.google.com/search/about-this-image?img=H4sIAAA...",
    "viewer_link": "https://www.google.com/imgres?imgurl=https%3A%2F%2Fsouthernstaircase.com%2Fwp-content%2Fuploads%..."
  },  {
    "position": 6,
    "title": "Spiral Staircase Folding Metal Stairs The Metropolitan (Diamond Plate Spiral Stairs) Paragon Stairs",
    "link": "https://affordableplaygrounds.com/?d=2697907071600&srsltid=AfmBOoreGgqFiGZh2kH...",
    "source": "affordableplaygrounds.com",
    "original": "https://aws.paragonstairs.com/wp-content/uploads/2017/06/07142420/the-metropol...",
    "original_width": 554,
    "original_height": 554,
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQA12...",
    "about_image_link": "https://www.google.com/search/about-this-image?img=H4sIAAA...",
    "viewer_link": "https://www.google.com/imgres?imgurl=https%3A%2F%2Faws.paragonstairs.com%2Fwp-content%2Fuploads%..."
  },  {
    "position": 7,
    "title": "Double Helix Staircases & Helical Stairs by Arcways",
    "link": "https://arcways.com/helical-stairs/",
    "source": "Arcways",
    "original": "https://arcways.com/wp-content/uploads/Arcways-custom-floating-glass-helical-s...",
    "original_width": 800,
    "original_height": 800,
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQjqU...",
    "about_image_link": "https://www.google.com/search/about-this-image?img=H4sIAAA...",
    "viewer_link": "https://www.google.com/imgres?imgurl=https%3A%2F%2Farcways.com%2Fwp-content%2Fuploads%2FArcways-..."
  },  {
    "position": 9,
    "title": "Spiral Staircase Design, Modern Method With Classic Solution",
    "link": "https://wooddesigner.org/spiral-staircase-design/",
    "source": "Wood Designer",
    "original": "https://wooddesigner.org/wp-content/uploads/2024/08/Hotel-Staircase-Spiral-Des...",
    "original_width": 800,
    "original_height": 538,
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSecm...",
    "about_image_link": "https://www.google.com/search/about-this-image?img=H4sIAAA...",
    "viewer_link": "https://www.google.com/imgres?imgurl=https%3A%2F%2Fwooddesigner.org%2Fwp-content%2Fuploads%2F202..."
  },  {
    "position": 10,
    "title": "Spiral Staircase Design Ideas",
    "link": "https://oakvalleydesigns.com/blogs/types-of-stairs/spiral-staircase-design-ide...",
    "source": "Oak Valley Designs",
    "original": "http://oakvalleydesigns.com/cdn/shop/articles/B0818_Spiral_staircase_design_id...",
    "original_width": 940,
    "original_height": 788,
    "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTdHY...",
    "about_image_link": "https://www.google.com/search/about-this-image?img=H4sIAAA...",
    "viewer_link": "https://www.google.com/imgres?imgurl=http%3A%2F%2Foakvalleydesigns.com%2Fcdn%2Fshop%2Farticles%2..."
  }]

Nine tiles are marked here; the response carries a hundred. Google lays the grid out as masonry rather than rows, so tile height varies with the image and the numbering follows the ranking, not the visual row.

search_metadata

search_metadata fields
field	type	default	description
id	string	–	Unique id of this search, `srx_` prefixed.
status	string	–	`success` on every 200.
created_at	string	–	When the search ran, ISO 8601 UTC.
took_ms	integer	–	End-to-end time to serve this response, in milliseconds.
parser_version	string	–	Dated version of the images parser that produced this response, so any response can be tied to the parsing behaviour that made it. Each vertical carries its own.
google_url	string	–	The exact Google URL fetched.
html_url	string	–	Archived copy of the results page exactly as served. Included when available.
json_url	string	–	Archived copy of this JSON response. Included when available.

search_parameters

The parameters the search actually ran with, defaults filled in. A filter appears only when you sent it.

search_parameters fields
field	type	default	description
q	string	–	The query as received.
gl	string	–	Country the search ran from, defaulting to `us`.
hl	string	–	Language used.
device	string	–	Device profile used.
page	integer	–	Page served.
image_size	string	–	Size bucket applied. Present when sent.
min_megapixels	integer	–	Megapixel floor applied. Present when sent.
image_color	string	–	Colour filter applied. Present when sent.
image_type	string	–	Type filter applied. Present when sent.

image_results

image_results entry fields
field	type	default	description
position	integer	–	Rank within the grid, starting at 1.
title	string	–	Title of the page the image sits on, as Google labels the tile.
link	string	–	The page hosting the image. Several tiles can share one page, so this does not identify a result on its own.
source	string	–	Publisher as displayed under the tile. Absent on tiles where Google prints no separate publisher line, which happens when the title already ends in the site name.
original	string	–	Full-size image on the publisher's server, at its own URL. This is the field that identifies a result uniquely.
original_width	integer	–	Width of the full-size image in pixels.
original_height	integer	–	Height of the full-size image in pixels.
thumbnail	string	–	Google's own small copy, served from its cache.
about_image_link	string	–	Google's “about this image” panel for this result, covering where the image has appeared before.
viewer_link	string	–	Google's own image viewer opened on this result, showing the image beside the page it came from.
date	string	–	Age of the page, as displayed. Only a few tiles carry one.
tags	list	–	Badges Google prints on the tile, such as `In stock` or `Licensable`.

Two lists of refined queries come back alongside the grid, both plain strings you can send straight back as q. related_searches is the block below the grid and is served on every page that has results. suggested_searches is the chip strip above the grid, which Google renders on the first page only.

They rarely repeat each other, so both are worth reading. Each is the whole query rather than the chip's on-screen label: Google prints Metal on a chip that searches metal spiral staircase, and the label alone is not a query.

pagination

Ask for the next page with page. Pages do not overlap: page 2 is a fresh hundred images, not the same grid shifted along. pagination.next is present only while another page exists, so its absence is how you know you have reached the end.

pagination fields
field	type	default	description
current	integer	–	The page this response is.
next	string	–	Google URL for the next page. Absent on the last one.

Errors

A rejected request answers with detail, naming the parameter and what to send in its place. A search that could not be completed answers with error and a search_id you can quote. No error is ever charged.

Status codes
field	type	default	description
401	unauthorized	−0	Missing, malformed, or revoked key. See Authentication.
402	payment required	−0	The balance can't cover a search. See Credits & billing.
422	invalid request	−0	Unknown or invalid parameter. The `detail` names the parameter and what to send in its place.
502	search_failed	−0	The search could not be completed. Retry it; you were not charged.
503	search_unavailable	−0	Google did not serve a usable results page. Retry it; you were not charged.

502 · search failed

HTTP/2 502
content-type: application/json
x-serpix-credits-charged: 0

{ "error": { "code": "search_failed", "search_id": "srx_kq3v9tR2xLw8mA1c" } }