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

Google Images search results as JSON: original image URL, thumbnail, exact pixel dimensions, title, source page and domain for every image. No browser, no API key. From $1.50 per 1,000 images.

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

## Pricing

from $1.00 / 1,000 image scrapeds

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

Turn Google Images into clean JSON. Give it one or more queries and get one row per image: the
**direct link to the original full-size image**, Google's thumbnail, the exact pixel dimensions, the title,
the page the image sits on, its domain and the site name — no browser, no API key, no scraping code to
maintain.

- **$1.50 per 1,000 images, no start fee.** You pay only for image rows that are delivered. Empty queries
  and failed queries cost nothing.
- Pure HTTP against Google's Images view, parsed from the page itself, so it is fast (about 5-8 s per
  page of ~100 images) and cheap to run.
- Country (`gl`), interface language (`hl`), SafeSearch and Google's own size / type / colour / time
  filters are supported.
- Every row carries a `status`, so a run that hit a block or an empty query explains itself instead of
  silently returning nothing.

### What you get

One dataset item per image:

| Field | Meaning |
| --- | --- |
| `query` | The query this image was found for. |
| `position` | 1-based rank within the query, in Google's order, across pages and after duplicates are dropped. |
| `title` | The title Google shows (usually the page title). |
| `imageUrl` | **Original** image file URL on the source site — not a Google thumbnail. |
| `thumbnailUrl` | Google's own thumbnail on `encrypted-tbn0.gstatic.com` (small, fast, always reachable). |
| `width`, `height` | Pixel size of the original image, as Google reports it. |
| `sourcePageUrl` | The page the image appears on (where Google's card links). |
| `sourceDomain` | That page's domain, e.g. `en.wikipedia.org`. |
| `sourceName` | The site name Google displays, e.g. `Wikipedia`, `Instagram`. |
| `scrapedAt` | ISO 8601 timestamp of the fetch. |
| `status` | `ok` for an image row, `empty` when Google had no images for the query, `error` when the query failed. |
| `error` | Reason for an `empty`/`error` row, otherwise `null`. |

### Input

```json
{
  "queries": ["red panda", "mid century modern sofa"],
  "gl": "us",
  "hl": "en",
  "maxImagesPerQuery": 50,
  "maxItems": 200,
  "safeSearch": true,
  "imageSize": "large",
  "imageType": "photo",
  "colour": "",
  "timeRange": ""
}
```

Only `queries` is required. A default run (one query, 50 images) costs about **$0.08**.

| Input | Default | Notes |
| --- | --- | --- |
| `queries` | — | Up to 50 queries. Duplicates and blank lines are dropped. |
| `gl` | `us` | Google country. Changes the result set and the regional mix of sites. |
| `hl` | `en` | Google interface language, e.g. `en`, `de`, `pt-BR`. |
| `maxImagesPerQuery` | `50` | 1-500. Google serves ~100 images per page, so 50 is one page. |
| `maxItems` | `200` | Run-wide cost ceiling across all queries. |
| `safeSearch` | `true` | Sends `safe=active`. |
| `imageSize` | any | `large`, `medium`, `icon` — Google's own size filter. |
| `imageType` | any | `photo`, `clipart`, `lineart`, `animated`. |
| `colour` | any | `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`, `white`, `gray`, `black`, `brown`, `blackandwhite`, `transparent`. |
| `timeRange` | any | `day`, `week`, `month`, `year`. |
| `concurrency` | `3` | Queries fetched in parallel (1-8). Pages of one query are always sequential. |

#### Filters

All four filters are Google's own: they are sent as Google's `tbs` parameter and applied by Google's
index, so the result set is exactly what a human sees after clicking the filter. For example
`imageSize: "large"` roughly halves the number of results and raises the smallest short side from 320 px
to 674 px, `imageType: "animated"` returns mostly `.gif` originals, and `colour: "red"` vs `"blue"`
share almost no results. Leave a filter empty for "any".

### Output example

A real row from a live run of this actor (`queries: ["red panda"]`):

```json
{
  "query": "red panda",
  "position": 1,
  "title": "Red Panda - SAFE Worldwide",
  "imageUrl": "https://safeworldwide.org/wp-content/uploads/2022/05/red-panda-2022-03-05-09-19-19-utc-scaled-e1653444292143-768x740.jpg",
  "thumbnailUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcT2_Z64mpT-r7D5_ueGW8FVDsUJ79nkKg-VzC4byVeW_g&s=10",
  "width": 768,
  "height": 740,
  "sourcePageUrl": "https://safeworldwide.org/red-panda/",
  "sourceDomain": "safeworldwide.org",
  "sourceName": "SAFE Worldwide",
  "scrapedAt": "2026-11-14T19:36:50.377Z",
  "status": "ok",
  "error": null
}
```

And a query with no images (delivered, not charged):

```json
{
  "query": "a query google has no images for",
  "position": null,
  "title": null,
  "imageUrl": null,
  "thumbnailUrl": null,
  "width": null,
  "height": null,
  "sourcePageUrl": null,
  "sourceDomain": null,
  "sourceName": null,
  "scrapedAt": "2026-11-14T19:36:50.377Z",
  "status": "empty",
  "error": "Google returned no images for this query"
}
```

### How many images can one query return?

Google's Images view serves about 100 images per page. This Actor walks Google's own result offset
(`start=0, 20, 40, ...`) and keeps going until it reaches `maxImagesPerQuery` or Google runs out.

Measured on 2026-11-15: page 1 and page 2 of `red panda` returned 100 images each with no overlap, and a
deeper offset returned Google's "there aren't any Images matches on this topic" page. For `cat`, pages 1-4
returned 100, 100, 46 and 49 images before Google stopped. So expect **up to a few hundred images per
query** — `maxImagesPerQuery` above that is harmless, the run just ends when Google has nothing more.
If you need more coverage, add more queries: that is how Google's Images index divides up.

### Cost

**$1.50 per 1,000 images** — about $0.0015 per image — with no monthly or start fee, roughly half of what
the most popular paid alternative charges for the same data. You are charged one `image-scraped` event
per delivered image row. Empty and error rows are free, a failed push is free, and the run stops by
itself at `maxItems` so a query you typed wrong cannot run up a bill.

### Notes, limits and honest caveats

- **Original image links can rot or block hotlinking.** `imageUrl` points at the source site's own file
  (that is what "original" means). Some hosts refuse requests without a referer, restrict hotlinking, or
  delete the file later. `thumbnailUrl` is Google's cached copy and is the more stable of the two; both
  are returned so you can fall back.
- **Dimensions are Google's numbers.** They come from Google's own metadata for the indexed image, which
  matched the real files in every check we made — but if the source site replaces the file, the numbers
  can drift from what you download.
- **Titles are Google's titles.** For social posts Google often shows the post text instead of a page
  title; the row is faithful to Google, not normalised.
- **Google's depth is finite.** There is no page 3 for every query (see above), and a few very broad
  queries return fewer results than their page count suggests.
- **Blocking is possible and handled, not eliminated.** The actor fetches through Apify's Google SERP
  proxy (included in the price; you do not need your own proxies), retries a blocked page with a fresh
  proxy session, and reports a query that never got through as an `error` row that is not charged. In
  normal testing we saw no CAPTCHA pages on this view, but Google can serve them to a tired proxy IP.
- **SafeSearch is on by default.** Turn it off only deliberately.
- **Results are Google's ranking for the `gl`/`hl` you asked for**, so the same query in `gl=us` and
  `gl=my` returns different sites.

### Run monitoring and privacy

If a run fails or times out, this Actor tells its developer the run ID and status, so we can fix problems fast. It never sends your input, your results or your account data.

# Actor input Schema

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

One or more Google Images searches, e.g. `red panda` or `mid century modern sofa`. Each query returns up to `maxImagesPerQuery` images. Maximum 50 queries per run.

## `gl` (type: `string`):

Two-letter Google country setting, which decides the result set and the regional mix of sites: us, gb, my, sg, de, au, in. `uk` is accepted and mapped to gb.

## `hl` (type: `string`):

Google interface language: en, de, fr, ja, pt-BR, zh-CN, es-419. This is the language of the Google UI and of the titles Google returns.

## `maxImagesPerQuery` (type: `integer`):

How many images to return per query (1-500, default 50). Google serves about 100 images per page, so 50 costs one page per query. Google rarely serves more than a few hundred images for a query; the actor stops as soon as a page comes back empty.

## `maxItems` (type: `integer`):

Global cost ceiling: the run stops after this many image rows across all queries (default 200, max 5000). At $0.0015 per image, 200 images cost $0.30 plus proxy usage. The default single query returns 50 images, so a default run costs about $0.08.

## `safeSearch` (type: `boolean`):

Send Google's SafeSearch filter (safe=active). On by default — the Store version of this Actor should not return adult images. Turn it off only if you have a reason to.

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

Google's own image-size filter. `large` returns the biggest originals (smallest short side measured: 674 px), `medium` the middle band, `icon` the small ones. Empty = any size.

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

Google's own image-type filter: photo, clipart (logos, drawings, PNG/SVG), lineart (black-and-white drawings) or animated (mostly GIFs). Empty = any type.

## `colour` (type: `string`):

Google's dominant-colour filter for the image itself, not for the query text. Empty = any colour.

## `timeRange` (type: `string`):

Only images from pages Google indexed recently: day, week, month or year. Useful for news and trends. Empty = any time.

## `concurrency` (type: `integer`):

How many queries are fetched in parallel (1-8, default 3). Pages of the same query are always fetched one after another. Higher is faster but uses more proxy sessions at once.

## Actor input object example

```json
{
  "queries": [
    "red panda"
  ],
  "gl": "us",
  "hl": "en",
  "maxImagesPerQuery": 50,
  "maxItems": 200,
  "safeSearch": true,
  "imageSize": "",
  "imageType": "",
  "colour": "",
  "timeRange": "",
  "concurrency": 3
}
```

# Actor output Schema

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

Dataset items: query, position, title, imageUrl (direct link to the original file), thumbnailUrl (Google's thumbnail), width, height, sourcePageUrl, sourceDomain, sourceName, scrapedAt, status (ok/empty/error) and error.

# 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": [
        "red panda"
    ],
    "gl": "us",
    "hl": "en",
    "maxImagesPerQuery": 50,
    "maxItems": 200,
    "concurrency": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("subimpact/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": ["red panda"],
    "gl": "us",
    "hl": "en",
    "maxImagesPerQuery": 50,
    "maxItems": 200,
    "concurrency": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("subimpact/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": [
    "red panda"
  ],
  "gl": "us",
  "hl": "en",
  "maxImagesPerQuery": 50,
  "maxItems": 200,
  "concurrency": 3
}' |
apify call subimpact/google-images-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,subimpact/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/l2maPBGeN8UCg2ZwG/builds/tZMGtvXao6iRPIkVb/openapi.json
