Name: Google Images API: Image Search Results as JSON
Brand: steadyscrape
SKU: api-steadyscrape-google-images
Availability: InStock
Author: API Market

# Google Images Search API

## Overview

The Google Images Search API returns Google Images results as JSON: for every image its rank, title, image URL, thumbnail, source page, site and size, plus a status row per search with the image count and related searches. You send up to 10 keyword searches per job, each with a country and language, and a depth of 1 to 100 results.

Jobs are asynchronous: `POST /v1/images/jobs` returns a job id and `GET /v1/images/jobs/{jobId}` returns the results when the job has `succeeded`, usually within 20 to 100 seconds per search. It is built for visual research, e-commerce and brand monitoring, dataset building and AI agents. In our tests a search for `red ceramic mug` in the US returned 10 images with their source pages, such as an 11-ounce mug on amazon.com at 1749 by 1464 pixels, and 20 related searches.

## Features

*   **2 endpoints**: start a job and poll it.
*   **Up to 10 searches**: per job, each with its own country and language.
*   **Image fields**: rank, title, image URL, thumbnail, source page, site, width and height.
*   **Related searches**: returned in the status row of each search.
*   **Fair billing**: one unit per image; searches with no images are free.

## Use Cases

*   **Visual research**: find images for a topic or product.
*   **E-commerce monitoring**: see which shops rank for a product image.
*   **Datasets**: collect image URLs for a set of keywords.
*   **AI agents**: give an agent an image search tool.

## API Documentation

### Base URL

All requests use the following base URL.

```
https://prod.api.market/api/v1/steadyscrape/google-images
```

### Authentication

All requests are authenticated with the `x-api-market-key` header.

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Start an image search job

Starts a job and returns its id.

**Method:** `POST`

**Endpoint:** `/v1/images/jobs`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `keywords` | body | Search terms, sharing `country` and `language` | array of strings | Yes, or `queries` | - | 10 |
| `country` | body | ISO country code, for example `us` | string | No | - | - |
| `language` | body | Language code, for example `en` | string | No | - | - |
| `depth` | body | Results per search | integer | No | - | 100 |
| `Idempotency-Key` | header | Optional key so a retried start is not run twice | string | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/steadyscrape/google-images/v1/images/jobs' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"keywords": ["red ceramic mug"], "country": "us", "language": "en", "depth": 10}'
```

**Example Response (202 Accepted):**

```json
{
  "success": true,
  "endpoint": "images.jobs",
  "count": 0,
  "partial": false,
  "items": [],
  "job": {
    "id": "a6b52dc83964dd0f06d194c8992690377418e80d652f8ac947adcd13fe63f70e",
    "status": "running",
    "partial": false,
    "truncated": false,
    "billable": false,
    "expiresAt": "2026-11-15T00:32:05.060Z"
  }
}
```

A request without searches returns `400`:

```json
{
  "success": false,
  "error": {
    "code": "bad_input",
    "message": "Send 1 to 10 searches in keywords or queries."
  }
}
```

#### 2. Poll an image search job

Returns the job status and, once it has succeeded, one status row per search and one row per image.

**Method:** `GET`

**Endpoint:** `/v1/images/jobs/{jobId}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `jobId` | path | The `job.id` from the start call | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/steadyscrape/google-images/v1/images/jobs/a6b52dc83964dd0f06d194c8992690377418e80d652f8ac947adcd13fe63f70e' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "success": true,
  "endpoint": "images.jobs",
  "count": 11,
  "partial": false,
  "items": [
    {
      "recordType": "queryStatus",
      "resultOrigin": "vendor",
      "queryIndex": 0,
      "keyword": "red ceramic mug",
      "country": "us",
      "language": "en",
      "queryStatus": "success",
      "stopReason": "none",
      "message": "Results returned.",
      "imageCount": 10,
      "duplicatesDropped": 0,
      "retrievedAt": "2026-11-14T00:32:08Z",
      "rank": null,
      "rankAbsolute": null,
      "title": null,
      "altText": null,
      "imageUrl": null,
      "thumbnailUrl": null,
      "sourcePageUrl": null,
      "sourceDomain": null,
      "sourceName": null,
      "width": null,
      "height": null,
      "dimensionsSource": null,
      "resultDatetime": null,
      "googleImagesUrl": "https://www.google.com/search?q=red+ceramic+mug&tbm=isch&hl=en&gl=US",
      "relatedSearches": [
        "Stoneware",
        "Logo",
        "Cork"
      ]
    },
    {
      "recordType": "image",
      "resultOrigin": "vendor",
      "queryIndex": 0,
      "keyword": "red ceramic mug",
      "country": "us",
      "language": "en",
      "queryStatus": "success",
      "stopReason": "none",
      "message": null,
      "imageCount": null,
      "duplicatesDropped": null,
      "retrievedAt": "2026-11-14T00:32:08Z",
      "rank": 1,
      "rankAbsolute": 2,
      "title": "Amazon.com: Funny Guy Mugs Plain Red Ceramic Coffee Mug, Red, 11-Ounce : Home & Kitchen",
      "altText": "Amazon.com: Funny Guy Mugs Plain Red Ceramic Coffee Mug, Red, 11-Ounce : Home & Kitchen",
      "imageUrl": "https://m.media-amazon.com/images/I/71BQ3o-SlzL.jpg",
      "thumbnailUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTeQ3LoOHewAwmpC1b2XDaZFQsEG3B0pfkEb78ez6EJ_w&s=10",
      "sourcePageUrl": "https://www.amazon.com/Funny-Guy-Mugs-Ceramic-11-Ounce/dp/B00BPWKQL0",
      "sourceDomain": "amazon.com",
      "sourceName": "Amazon.com",
      "width": 1749,
      "height": 1464,
      "dimensionsSource": "image_header",
      "resultDatetime": "2026-11-14T00:32:11Z",
      "googleImagesUrl": null,
      "relatedSearches": null
    }
  ],
  "job": {
    "id": "a6b52dc83964dd0f06d194c8992690377418e80d652f8ac947adcd13fe63f70e",
    "status": "succeeded",
    "partial": false,
    "truncated": false,
    "billable": true,
    "expiresAt": "2026-11-15T00:32:05.060Z"
  }
}
```

The `items` list above is shortened to the status row and the first of 10 images.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the JSON result is in the response body. |
| 202 | Accepted | The job was accepted (start) or is still running (poll). Poll again after a few seconds. |
| 400 | Bad Request | The body is invalid, for example no URL or keyword. The message says what to send. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key does not have an active subscription that includes this endpoint. |
| 404 | Not Found | The job id is unknown or the job has expired (jobs are kept 24 hours). |
| 429 | Too Many Requests | You went over 10 requests per second, used up your plan, or the service is busy. Retry after a short wait. |
| 500 | Internal Server Error | The request failed on the server. Retry once, then contact us if it continues. |
| 503 | Service Unavailable | The service is temporarily unavailable. Retry after a short wait. |

## Rate Limits

Every plan allows up to 10 requests per second. The Free trial includes 20 units. Starter includes 800 units per month for $9.99, Pro 3,000 for $29.99 and Business 9,000 for $79.99. Starting a job and polling it use no units; units are charged only for usable results, reported in the response that finishes the job. When you go over a limit, the API returns `429 Too Many Requests`. Throttle your requests, back off before retrying, and honour the `Retry-After` header when it is present.

## FAQ

*   **How do I get the result?**
    Start a job with `POST`, keep the `job.id`, and call the poll endpoint every few seconds until `job.status` is `succeeded` (or `failed`). Results are kept for 24 hours.

*   **Why did I get a busy response?**
    The service runs a limited number of searches at once and returns `429` with code `busy` when it is full. Retry after a few seconds.

*   **Are search operators supported?**
    No. Search operators and personal identifiers are refused.

*   **What is billed?**
    Only usable results, one unit each. Starting a job, polling, refused or failed items and empty results are free.

## Contact Us

If you have any questions or need support, reach out through the chat embedded on this page or email us at hello@magicapi.com.


Google Images search API: image URL, thumbnail, source page, title, rank and size as JSON for up to 10 searches per job, with related searches.

Google Images API: Image Search Results as JSON