Images Search

POST

/api/v1/images

The images search endpoint retrieves high-resolution photos, stock graphics, diagrams, and illustrations matching your search term.

Results include direct image source URLs, thumbnail previews, pixel dimensions, originating website links, and position rankings.

Returned Image Properties

Each result in the images response array contains structured visual metadata:

title: Descriptive caption or alt text from the hosting website
imageUrl: Direct HTTP link to the full-resolution image asset
imageWidth: Image width in pixels
imageHeight: Image height in pixels
link: URL of the web page where the image was discovered
position: Numeric search engine rank position (1-based)

{
  "q": "cute kittens",
  "gl": "us",
  "hl": "en",
  "num": 10
}

Authorizations

X-API-KEYstringheaderrequired

Passed via request headers. Your secret API key for SerperMatrix (e.g. sm_live_...).

Body

application/json

qstringrequired

The search query string you want to use to locate matching images (e.g. "cute kittens").

glstring

Geographic location country code for regional targeting (e.g. "us", "uk").

hlstring

Host language code for localized metadata (e.g. "en", "es").

locationstring

Exact localized location boundary string for hyper-targeted results.

numintegerdefault: 10

Number of image results to retrieve (min: 1, max limit: 100).

pageintegerdefault: 1

Result page offset.

use_cachebooleandefault: true

Retrieve cached response if available (caches up to 1 hour).

Request

curl -X POST https://serpermatrix.com/api/v1/images \
  -H "X-API-KEY: sm_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"q":"cute kittens","num":2}'

{
  "searchParameters": {
    "q": "cute kittens",
    "num": 2,
    "type": "images"
  },
  "images": [
    {
      "title": "Cute Kittens Stock Photos, Images & Pictures",
      "imageUrl": "https://images.unsplash.com/photo-1514888286974-6c03e2ca1dba",
      "imageWidth": 1200,
      "imageHeight": 800,
      "link": "https://unsplash.com/s/photos/cute-kittens",
      "position": 1
    }
  ]
}