# Google Images API (`steady-scrape/google-images-api`) Actor

Google Images results as JSON: image URL, thumbnail, source page and site, title, rank, width and height, and related searches. Pay per query with images; empty queries are free.

- **URL**: https://apify.com/steady-scrape/google-images-api.md
- **Developed by:** [SteadyScrape](https://apify.com/steady-scrape) (community)
- **Categories:** E-commerce, SEO tools, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 query with images

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Google Images API for Product Image Research

**Who it's for:** ecommerce, catalog, SEO and brand teams who need to see which images Google shows for a keyword, plus developers and AI agents who need Google Images results as clean JSON.

**What you get:** for each keyword, up to 100 ranked Google Images results with the **image URL, Google thumbnail, source page, site name, title, alt text, rank, and width and height**, plus **related searches** and a link to the same Google Images page. You get metadata and links only: image files are not downloaded in full or rehosted.

**Price:** $0.010 per query that returns at least one image, plus $0.002 once per run that has such a query. A query that finds no images is free, and so are failed or timed-out queries. 1 query with images = $0.012. 10 queries with images in one run = $0.102.

Made by **SteadyScrape (steady-scrape)**.

### What you can do with it

1. **Product image research.** See which product photos, sites and angles rank for "red ceramic mug" in the US, UK or Germany.
2. **Brand and marketplace monitoring.** Check whose images appear for your brand or product names, and on which sites.
3. **SEO and content audits.** Find the image sizes and source pages that win image results for your target keywords.
4. **Keyword discovery.** Use `relatedSearches` to find the next keywords buyers type.
5. **Datasets for AI agents and apps.** Get Google Images results as JSON through the Apify API or MCP.

### Input

Simple form: a list of keywords that share one country and language.

```json
{
  "keywords": ["red ceramic mug", "blue ceramic bowl"],
  "country": "us",
  "language": "en",
  "depth": 100,
  "fillDimensions": true
}
```

Advanced form: a different country and language for each search. You can combine both forms, up to 10 searches per run.

```json
{
  "queries": [
    { "keyword": "red ceramic mug", "country": "us", "language": "en" },
    { "keyword": "rote Keramiktasse", "country": "de", "language": "de" }
  ]
}
```

- **depth**: images kept per query, from 1 to 100 (one result page).
- **fillDimensions** (default on): fills in width and height by reading only the first bytes of each image file (see below).
- **dryRun**: test mode with labeled sample rows. No search is run and nothing is charged.
- Country codes are ISO two-letter codes (`uk` is accepted as `gb`). Chinese must be `zh-CN` or `zh-TW`.

### Output

Each query gets one status row (`recordType: "queryStatus"`) and one row per image (`recordType: "image"`).

| Field | Meaning |
| --- | --- |
| `rank`, `rankAbsolute` | Position in the image results |
| `title`, `altText` | Result title and image alt text |
| `imageUrl` | Source image URL |
| `thumbnailUrl` | Google's cached thumbnail |
| `sourcePageUrl`, `sourceDomain`, `sourceName` | The page that shows the image, its domain, and the site name Google shows |
| `width`, `height` | Pixel size, read from the image header when `fillDimensions` is on. Null when it could not be read |
| `dimensionsSource` | `image_header`, `provider`, or null |
| `queryStatus` | `success`, `partial`, `empty`, `timeout`, `failed`, `provider_error`, `malformed_response`, `blocked_operator`, `unsupported_locale`, `not_run`, or `invalid_input` |
| `googleImagesUrl` | Status rows only: the Google Images page for that query |
| `relatedSearches` | Status rows only: related searches Google showed |
| `imageCount`, `duplicatesDropped`, `dimensionsFilled` | Status rows only: counts for that query |
| `retrievedAt`, `resultDatetime` | When the row was prepared, and the upstream result time |

`partial` means the search returned images, but a few results were incomplete and were left out. The `OUTPUT` record summarizes every query and its status.

Sample image row (shortened):

| rank | title | sourceName | width | height | imageUrl |
| --- | --- | --- | --- | --- | --- |
| 1 | Red ceramic mug on a table | example.com | 1200 | 1200 | https://images.example.com/mugs/red-ceramic.jpg |

### Image size fill-in

The search results don't include pixel sizes. When `fillDimensions` is on, the Actor asks each image host for only the first bytes of the file with a range request, and stops reading as soon as the size is found. It never downloads or stores the whole file. It reads PNG, JPEG, GIF, WebP, BMP and AVIF/HEIF, and contacts public hosts only.

Each query gets about 12 seconds for this step, so some sizes can stay null. Some sites also refuse these requests. Fill-in never fails a query, never changes its status or image count, and doesn't change the price. Turn it off for the fastest runs.

### Pricing

| Event | Price | When |
| --- | --- | --- |
| `successful-query` | $0.010 | per query that returns at least one image (`success`, or `partial` with at least one image) |
| `run-with-success` | $0.002 | once per run, only if at least one query returned images |
| `apify-actor-start` | $0.00005 | Apify's standard per-run start event |

Free: queries that find no images, failed or timed-out queries, blocked or invalid input, and test mode.

Examples: 1 query with images = $0.012. 10 queries with images in one run = $0.102. A run where every query is empty = $0.000 (plus the Apify start event).

You can set a maximum cost per run in Apify. The Actor stops sending new searches when the next one would go past it.

### Limits

- Up to 10 searches per run and up to 100 images per search. Searches run one at a time.
- Each search is one instant request that can take up to about 95 seconds. A request that may already have been answered is never sent twice, so you are not charged twice.
- Advanced operators (`site:`, `related:`, a leading minus and look-alikes) are rejected and free. The Actor also rejects email addresses, phone numbers and profile links. Do not submit person or face lookups.
- Live search needs a paid Apify plan. On the free plan, runs return a clear `not_run` status and are free.
- The run needs a maximum cost per run of at least $0.012 to cover one query.

### How it compares

- **Copying results by hand:** fine for one keyword. This gives you 100 ranked rows per keyword, for many countries, as a spreadsheet or JSON.
- **Building your own scraper:** Google Images pages change often and need proxies and upkeep. Here you send keywords and get structured rows.
- **General image search APIs:** many return image links only. This adds source page, site name, rank, related searches, and real pixel sizes read from the image files.
- **You only pay for searches that return images.** Empty, failed and timed-out searches cost nothing.

### FAQ

**Does it download the images?** No. It returns links and metadata. With `fillDimensions` on, it reads only the first bytes of each file to get the size.
**Can I use the images?** Results are search metadata. They grant no reuse, training or copyright rights. Check each image's source page.
**Why are some width/height values null?** Some hosts refuse partial reads or answer slowly, and the size step is time-limited.
**What does `partial` mean?** Images were returned, but a few results were incomplete and left out. It is charged like a success, because you got images.
**How fresh are results?** Each run is a new Google Images search for your country and language.

### Integrations

- **Apify API and SDKs:** call it from Python, JavaScript or any HTTP client and read the run's dataset.
- **Schedules and webhooks:** run it on a schedule and trigger your own endpoint when a run finishes.
- **Make, Zapier, n8n:** use Apify's integrations to start runs and pass rows on.
- **AI agents (MCP):** agents can call it through the Apify MCP server.

### Data source & terms

Image search results and metadata are sourced from Google Images via the DataForSEO API. The service is not affiliated with or endorsed by Google. Data is provided for research and analytics of the keywords the customer selects, and may not be used to create a service that competes with general search engines. Returned links are search metadata: this Actor does not download in full, rehost or license images, and grants no reuse, training or copyright clearance. It is not a face search, a person directory or a reverse-image search. The service is not offered to customers in Russia, Belarus, Syria, North Korea, or occupied Crimea.

### More from SteadyScrape

- [Google Rank Tracker](https://apify.com/steady-scrape/google-rank-tracker): track where your pages rank on Google for the keywords you care about.
- [Keyword Search Volume](https://apify.com/steady-scrape/keyword-search-volume): Google search volume, CPC, competition and a 12-month trend for your keywords.
- [Amazon Keyword Research & Rank Tracker](https://apify.com/steady-scrape/amazon-keyword-research-rank-tracker): Amazon keyword ideas and product rank tracking for your listings.

See every **SteadyScrape (steady-scrape)** Actor on [our Apify profile](https://apify.com/steady-scrape).

# Actor input Schema

## `keywords` (type: `array`):

Plain search phrases, one per line. Each uses the country and language below. Up to 10 searches per run, counting any advanced queries. Personal identifiers and search operators are rejected.

## `country` (type: `string`):

ISO 3166-1 alpha-2 country code for the keyword list, for example us. The code uk is accepted as gb.

## `language` (type: `string`):

Language code for the keyword list, for example en. Chinese must be zh-CN or zh-TW.

## `queries` (type: `array`):

Optional. Up to 10 searches, each with its own keyword, ISO country code, and ISO language code. Use this instead of, or together with, the keyword list. Do not submit personal data, profile lookups, or search operators.

## `depth` (type: `integer`):

Maximum images kept for each query. The hard cap is 100, which is a single result page. Extra pages cannot be requested.

## `fillDimensions` (type: `boolean`):

When on, the actor reads only the first bytes of each image file to find its width and height. Whole files are not downloaded. Sizes that cannot be read stay null and never fail the run.

## `dryRun` (type: `boolean`):

Test mode: return labeled sample rows without running a search. Nothing is charged.

## Actor input object example

```json
{
  "keywords": [
    "red ceramic mug"
  ],
  "country": "us",
  "language": "en",
  "depth": 100,
  "fillDimensions": true,
  "dryRun": false
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset rows for image metadata and query statuses.

## `summary` (type: `string`):

Run summary stored in the default key-value store.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "keywords": [
        "red ceramic mug"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("steady-scrape/google-images-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "keywords": ["red ceramic mug"] }

# Run the Actor and wait for it to finish
run = client.actor("steady-scrape/google-images-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "keywords": [
    "red ceramic mug"
  ]
}' |
apify call steady-scrape/google-images-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,steady-scrape/google-images-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/itNNWWlrjLYvPKrTU/builds/9TbVXPusID8qYPcoJ/openapi.json