# Google Images Scraper (`solidcode/google-images-scraper`) Actor

\[💰 $1.8/1K] Extract image results from Google Imagesm image URLs, thumbnails, dimensions, titles, source pages, and domains. Batch multiple queries, paste full image-search URLs, and filter by size, color, type, aspect ratio, time, and usage rights. Localized across 45+ countries and 20+ languages.

- **URL**: https://apify.com/solidcode/google-images-scraper.md
- **Developed by:** [SolidCode](https://apify.com/solidcode) (community)
- **Categories:** Developer tools, Automation, SEO tools
- **Features:** Limited permissions
- **Stats:** 147 total users, 8 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.80 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 Scraper

Pull image search results from Google Images at scale — full-resolution image URLs, pixel dimensions, file size, source domains, source-page titles, Google-hosted thumbnails, and a `docid` join key for every tile. Filter by 16 dominant colors, 5 aspect ratios, 6 image types, 6 time windows, 3 license buckets, 3 size brackets, and SafeSearch — across 250 countries and 208 interface languages. Built for creative teams, e-commerce catalogers, and ML dataset builders who need clean, structured image data without clicking through Google one tile at a time.

### Why This Scraper?

- **18 typed fields per image** — `imageUrl`, `imageWidth`, `imageHeight`, `thumbnailUrl`, `thumbnailWidth`, `thumbnailHeight`, `sourceUrl`, `sourceDomain`, `sourceTitle`, `title`, `imageBytes`, `docid`, `position`, `googleUrl`, `searchUrl`, `query`, `scrapedAt`, `recordType`. No HTML, no post-processing.
- **Direct full-resolution image URLs, not just thumbnails** — every row carries the original `imageUrl` with pixel `imageWidth` x `imageHeight` and the human-readable `imageBytes` Google reports (e.g. `"214KB"`).
- **16 dominant-color filters** — full color, black & white, transparent background, plus 12 named colors (red, orange, yellow, green, teal, blue, purple, pink, white, gray, black, brown). Match a brand palette in one input.
- **Up to 260 unique images per query** — hits Google's own per-query ceiling with automatic pagination across `start=0/10/20/30` and docid-level deduplication.
- **Every Google Images filter wired into a dropdown** — 5 aspect ratios (Tall, Square, Wide, Panoramic), 6 image types (Photo, Clip art, Line drawing, GIF, Animated), 6 time windows (hour, 24h, week, month, year), 3 license buckets (Creative Commons, Commercial), and 3 size brackets (Large, Medium, Icon).
- **250 countries and 208 interface languages** — full coverage of every regional Google frontend, with the `Accept-Language` header auto-matched to your `language` choice so `hl=` actually changes results.
- **`includeRelatedQueries` for keyword expansion** — toggles a bonus `recordType: "relatedQueries"` row per query carrying Google's "Related searches" chips, ready for trend research.
- **Stable `docid` join key on every row** — Google's internal document identifier survives across runs, so you can dedupe, diff, and join scrape outputs over time.
- **Paste any Google Images URL** — power users can craft a search visually with `tbs=` filters, copy the URL, and drop it in; every encoded filter is preserved.

### Use Cases

**Marketing, Creative & Brand**

- Build mood boards filtered by dominant color to match a brand palette
- Source on-brand stock candidates by combining `imageType: "photo"` with a Creative Commons license filter
- Track how a campaign visual is being repurposed across the open web

**E-commerce & Product Catalogs**

- Pull reference photography for new SKUs from a batch of product names
- Collect competitor packaging shots filtered to `imageType: "photo"` and `aspectRatio: "square"`
- Build hero-image candidates for category pages by aspect ratio

**Market & Consumer Research**

- Run the same query across multiple `country` codes to map regional visual differences
- Use the `includeRelatedQueries` output for keyword-expansion research
- Track meme and trend imagery week-over-week with the `pastWeek` time filter

**SEO & Digital Marketing**

- Audit which `sourceDomain` values dominate Google Images for target keywords
- Map the source pages Google rewards with image visibility for branded vs. non-branded terms
- Diff visibility across a 12-month window with the `pastYear` filter

**ML, Computer Vision & Datasets**

- Build training sets pre-filtered to Creative Commons with width/height included for resolution gating
- Seed image-recognition pipelines with query-tagged URLs and the `docid` as a stable join key
- Generate per-class folders by running batched queries with shared filter settings

### Getting Started

#### Simple Search

The fastest way to start — just a keyword:

```json
{
    "queries": ["golden retriever puppies"],
    "maxResultsPerQuery": 100
}
```

#### Multi-Query with Filters

Run several queries with the same filters applied to every one:

```json
{
    "queries": ["minimalist kitchen", "scandinavian living room", "japandi bedroom"],
    "maxResultsPerQuery": 200,
    "imageSize": "large",
    "imageType": "photo",
    "aspectRatio": "wide",
    "imageColor": "white",
    "usageRights": "creativeCommons",
    "safeSearch": "moderate",
    "country": "us",
    "language": "en",
    "includeRelatedQueries": true
}
```

#### Paste a Google Images URL

Already built the perfect search in Google's UI? Copy the URL from your browser bar and drop it in:

```json
{
    "searchUrls": [
        "https://www.google.com/search?q=sunset+over+mountains&udm=2&tbs=isz:l,itp:photo,ic:specific,isc:orange"
    ],
    "maxResultsPerQuery": 150
}
```

Any filters already encoded in the URL are preserved exactly as you set them.

#### Localized Search — Match Country and Language

Pull German-hosted results with a German interface:

```json
{
    "queries": ["kuchen"],
    "country": "de",
    "language": "de",
    "maxResultsPerQuery": 100
}
```

### Input Reference

#### Search

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `queries` | string\[] | `["golden retriever puppies"]` | Keywords to search on Google Images. Each query runs independently and produces its own image set. Up to 100 queries and URLs combined per run. |
| `searchUrls` | string\[] | `[]` | Paste full Google Images result URLs. Filters encoded in the URL are preserved verbatim. |
| `maxResultsPerQuery` | integer | `100` | Maximum images per query or URL. Set `0` for all available. Google caps each query at roughly 260 unique images. |

#### Filters

All filters are optional — leave on the defaults for no filter.

| Parameter | Type | Default | Options |
|-----------|------|---------|---------|
| `imageSize` | string | `any` | Any size, Large, Medium, Icon |
| `imageColor` | string | `any` | Any color, Full color, Black and white, Transparent background, Red, Orange, Yellow, Green, Teal, Blue, Purple, Pink, White, Gray, Black, Brown |
| `imageType` | string | `any` | Any type, Photo, Clip art, Line drawing, GIF, Animated |
| `aspectRatio` | string | `any` | Any aspect, Tall (portrait), Square, Wide (landscape), Panoramic |
| `timePeriod` | string | `anytime` | Anytime, Past hour, Past 24 hours, Past week, Past month, Past year |
| `usageRights` | string | `any` | Any license, Creative Commons licenses, Commercial & other licenses |
| `safeSearch` | string | `off` | Off, Moderate, Strict |

The `usageRights` filter surfaces images Google has classified under each license bucket. Always verify the license at the source page before using any image commercially.

#### Localization

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `language` | string | `en` | Interface language. 208 options spanning English, Spanish (8 regional variants), Portuguese (Brazil, Portugal), Chinese (Simplified, Traditional, Hong Kong), Japanese, Korean, Arabic, Hindi, and 190+ more. |
| `country` | string | `us` | Country code for the regional Google frontend. 250 options covering every country Google supports. |

#### Enrichment

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `includeRelatedQueries` | boolean | `false` | Emit a `recordType: "relatedQueries"` row per query carrying Google's "Related searches" suggestions. |

### Output

Every row carries a `recordType` field — `image` or `relatedQueries` — so downstream filtering is one column away.

#### Image record (`recordType: "image"`)

```json
{
    "recordType": "image",
    "query": "golden retriever puppies",
    "position": 1,
    "title": "Golden Retriever Puppy Playing in the Grass",
    "imageUrl": "https://example-media.com/uploads/puppy-hero.jpg",
    "imageWidth": 1600,
    "imageHeight": 1067,
    "thumbnailUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9Gc...",
    "thumbnailWidth": 276,
    "thumbnailHeight": 183,
    "sourceUrl": "https://example-media.com/blog/golden-retriever-puppies",
    "sourceDomain": "example-media.com",
    "sourceTitle": "Golden Retriever Puppies — A Complete Guide",
    "imageBytes": "214KB",
    "googleUrl": "https://www.google.com/imgres?docid=abc123...",
    "searchUrl": "https://www.google.com/search?q=golden+retriever+puppies&udm=2&gl=us&hl=en&start=0",
    "docid": "0wJpF3VkXlABcM",
    "scrapedAt": "2026-04-22T14:32:11Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `recordType` | string | Always `"image"` for image rows |
| `query` | string | The keyword that produced this result (or the auto-extracted query for pasted URLs) |
| `position` | integer | 1-based rank of the image within its query |
| `title` | string | Image title or alt text as surfaced by Google |
| `imageUrl` | string | Direct URL to the full-resolution image |
| `imageWidth` | integer | Full-resolution width in pixels |
| `imageHeight` | integer | Full-resolution height in pixels |
| `thumbnailUrl` | string | Google-hosted, CDN-stable thumbnail URL |
| `thumbnailWidth` | integer | Thumbnail width in pixels |
| `thumbnailHeight` | integer | Thumbnail height in pixels |
| `sourceUrl` | string | URL of the page where the image was found |
| `sourceDomain` | string | Hostname of the source page (e.g. `example-media.com`) |
| `sourceTitle` | string | Title of the source page |
| `imageBytes` | string | Human-readable file size as reported by Google (e.g. `"214KB"`) |
| `googleUrl` | string | Google's in-product image preview URL |
| `searchUrl` | string | The exact Google Images URL this result was scraped from (query + filters + pagination) |
| `docid` | string | Google's internal document identifier — stable join key across runs |
| `scrapedAt` | string | ISO 8601 UTC timestamp of when the row was captured |

#### Related-queries record (`recordType: "relatedQueries"`)

Emitted only when `includeRelatedQueries: true`. One row per query.

```json
{
    "recordType": "relatedQueries",
    "query": "nike shoes",
    "relatedQueries": ["Air max", "Air force", "High top", "Sneaker", "Basketball"],
    "scrapedAt": "2026-04-22T14:32:47Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `recordType` | string | Always `"relatedQueries"` |
| `query` | string | The source query Google suggested these refinements for |
| `relatedQueries` | string\[] | Array of Google's "Related searches" suggestions |
| `scrapedAt` | string | ISO 8601 UTC timestamp of when the row was captured |

### Tips for Best Results

- **Google caps every query at ~260 unique images** — this is a platform-wide ceiling, identical whether you scroll Images yourself or use any tool. To exceed it, split broad queries into specific variants (`"nike air max"` + `"nike air force"` + `"nike dunk"` instead of `"nike shoes"`) and run them as a batch.
- **Match `country` and `language`** — pairing `country: "de"` with `language: "de"` returns German-hosted results with a German interface; mismatching the two can silently dilute the result set with cross-locale tiles.
- **Use `searchUrls` for power-user filter combos** — Google's UI exposes some filter mixes (e.g. `imageColor: "orange"` + `aspectRatio: "panoramic"` + `timePeriod: "pastWeek"`) that are easier to compose visually. Build the search in your browser, copy the URL, paste it in.
- **Enable `includeRelatedQueries` on a topic-discovery run** — one extra row per query gives you Google's keyword-expansion list for free, so you don't need a separate run to find adjacent search terms.
- **Verify licenses at the source page** — the `usageRights` filter reflects how Google classifies each image, but licensing on the host page can change. Click through to `sourceUrl` before any commercial use.
- **Use `docid` to dedupe across runs** — the same image can re-enter the result set under different queries or on different days. The `docid` is Google's stable identifier — group on it before merging datasets.
- **Start small, then scale** — try `maxResultsPerQuery: 50` first to confirm the filter combination matches what you want, then bump to 200–260 per query for the production run.

### Pricing

**From $1.8 per 1,000 results** — the lowest price on Apify for Google Images data.

| Results | Estimated Cost |
|---------|----------------|
| 100 | $0.18 |
| 1,000 | $1.80 |
| 10,000 | $18.00 |
| 100,000 | $180.00 |

A "result" is any row in the output dataset — an image or a related-queries record. Platform fees (compute, storage) are additional and depend on your Apify plan.

### Integrations

Export data in JSON, CSV, Excel, XML, or RSS. Connect to 1,500+ apps via:

- **Zapier** / **Make** / **n8n** — Workflow automation
- **Google Sheets** — Direct spreadsheet export
- **Slack** / **Email** — Notifications on new results
- **Webhooks** — Trigger custom APIs on run completion
- **Apify API** — Full programmatic access

### Legal & Ethical Use

This actor is designed for legitimate market research, competitive analysis, creative inspiration, and dataset building. Users are responsible for complying with applicable laws and Google's Terms of Service. Image copyright belongs to the original creator — always verify licensing at the source page before reusing any image commercially. Do not use extracted data for spam, harassment, copyright infringement, or any illegal purpose.

# Actor input Schema

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

Keywords to search on Google Images (e.g., 'golden retriever puppies' or 'minimalist kitchen'). Each query runs independently and returns its own set of images. Maximum 100 queries and URLs combined per run — split larger batches across multiple runs. Leave empty if you only want to scrape pasted image-search URLs.

## `searchUrls` (type: `array`):

Optional: paste full Google Images result URLs (e.g., 'https://www.google.com/search?q=sunset\&udm=2\&tbm=isch'). Any filters already encoded in the URL are preserved, so this is handy for power users who built a search in Google's UI. Maximum 100 queries and URLs combined per run.

## `maxResultsPerQuery` (type: `integer`):

Maximum number of images to return per query or URL. Set to 0 for all available results. Google Images caps each query at roughly 260 unique images — values above that return whatever Google has available, never more.

## `imageSize` (type: `string`):

Filter by full-resolution size.

## `imageColor` (type: `string`):

Filter by dominant color. 'Transparent' returns images with alpha channels (usually PNG).

## `imageType` (type: `string`):

Filter by image type.

## `aspectRatio` (type: `string`):

Filter by image orientation / aspect ratio.

## `timePeriod` (type: `string`):

Only include images indexed within this time window.

## `usageRights` (type: `string`):

Filter by license. 'Creative Commons' includes all CC-licensed images; 'Commercial & other licenses' surfaces images marked for commercial use. Always verify the license directly at the source page before using any image commercially.

## `safeSearch` (type: `string`):

Google's SafeSearch filter. 'Off' disables filtering entirely; 'Moderate' and 'Strict' both enable SafeSearch (Google itself no longer distinguishes the two in image search — both hide explicit results).

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

Language of the Google Images interface (hl parameter). Affects result titles and the interface locale.

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

Country code (gl) for localized results. Affects which regional Google frontend is used.

## `includeRelatedQueries` (type: `boolean`):

Also emit a row per query containing Google's 'Related searches' suggestions. Useful for keyword expansion and trend research.

## Actor input object example

```json
{
  "queries": [
    "golden retriever puppies"
  ],
  "searchUrls": [],
  "maxResultsPerQuery": 100,
  "imageSize": "any",
  "imageColor": "any",
  "imageType": "any",
  "aspectRatio": "any",
  "timePeriod": "anytime",
  "usageRights": "any",
  "safeSearch": "off",
  "language": "en",
  "country": "us",
  "includeRelatedQueries": false
}
```

# Actor output Schema

## `images` (type: `string`):

Table of image results with title, URL, dimensions, and source info.

## `related` (type: `string`):

Rows of related-search suggestions per query (only present when 'Include Related Queries' is enabled).

# 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 = {
    "queries": [
        "golden retriever puppies"
    ],
    "searchUrls": [],
    "maxResultsPerQuery": 100,
    "imageSize": "any",
    "imageColor": "any",
    "imageType": "any",
    "aspectRatio": "any",
    "timePeriod": "anytime",
    "usageRights": "any",
    "safeSearch": "off",
    "language": "en",
    "country": "us",
    "includeRelatedQueries": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("solidcode/google-images-scraper").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 = {
    "queries": ["golden retriever puppies"],
    "searchUrls": [],
    "maxResultsPerQuery": 100,
    "imageSize": "any",
    "imageColor": "any",
    "imageType": "any",
    "aspectRatio": "any",
    "timePeriod": "anytime",
    "usageRights": "any",
    "safeSearch": "off",
    "language": "en",
    "country": "us",
    "includeRelatedQueries": False,
}

# Run the Actor and wait for it to finish
run = client.actor("solidcode/google-images-scraper").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 '{
  "queries": [
    "golden retriever puppies"
  ],
  "searchUrls": [],
  "maxResultsPerQuery": 100,
  "imageSize": "any",
  "imageColor": "any",
  "imageType": "any",
  "aspectRatio": "any",
  "timePeriod": "anytime",
  "usageRights": "any",
  "safeSearch": "off",
  "language": "en",
  "country": "us",
  "includeRelatedQueries": false
}' |
apify call solidcode/google-images-scraper --silent --output-dataset

```

## MCP server setup

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

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/1zP0mfnAf2xvIwvJu/builds/xkFsiO6iiz4CNvDZm/openapi.json