# Product Image Gallery Extractor (`eichan/product-image-gallery-extractor`) Actor

- **URL**: https://apify.com/eichan/product-image-gallery-extractor.md
- **Developed by:** [Eichan Jolly](https://apify.com/eichan) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$3.00 / 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.

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

## Product Image Gallery Extractor

Extract the product image links that one public product page **actually declares** in its schema.org `Product` JSON-LD and `og:image` meta tags. No browser, proxy, login, guessing filenames, or image downloads.

### Who is this for?

Merchants auditing product image metadata, catalogue QA analysts, and developers preparing image lists for a product import. **One product page per run**; it is not a full-site scraper.

### Quick start / real prefilled demonstration

The Apify input form is prefilled with a publicly reachable Cancork product page whose `og:image` URL was independently observed on **2026-11-01**. The page may change after that date.

```json
{
  "productUrl": "https://www.cancork.com/store/wood-bricks-9mm-cork-wall-panels/"
}
```

Expected at least one result from its currently published `og:image` tag, provided the website still exposes it:

```json
{
  "productUrl": "https://www.cancork.com/store/wood-bricks-9mm-cork-wall-panels/",
  "imageUrl": "https://www.cancork.com/product-images/wood-bricks-9mm-cork-wall-panels-wall-interior-ge.webp",
  "source": "og_image",
  "position": 1,
  "status": "ok",
  "error": null
}
```

A different page with explicit JSON-LD product images emits `source: "jsonld"`. One clean dataset item is emitted for **each unique URL**. Results use 1-based `position`, with JSON-LD images before Open Graph images. If the same URL appears in both, only the first JSON-LD occurrence is retained.

### Output fields

- `productUrl` (string): exact validated page URL provided, normalized with a `/` if path omitted.
- `imageUrl` (string or null): image URL explicitly referenced on the page.
- `source` (`jsonld`, `og_image`, or null): where that particular URL was found.
- `position` (positive integer or null): order within this run's deduplicated results.
- `status` (`ok`, `not_found`, or `error`).
- `error` (string or null): plain-language reason if no data is available.

If neither source declares an image, the Actor emits one honest not-found item rather than inventing an image:

```json
{
  "productUrl": "https://example.org/public-product",
  "imageUrl": null,
  "source": null,
  "position": null,
  "status": "not_found",
  "error": "No product JSON-LD images or og:image tags were found."
}
```

The URL above is an **illustrative output shape only**, not the prefilled demo URL.

### Data sources and limits

- Fetches only the **one product URL supplied**, no sitemap crawling and no additional image requests.
- Parses `application/ld+json` blocks and `image` strings, arrays, or `ImageObject` `url`/`contentUrl` values within objects of type `Product`, including `@graph` entries. Non-Product structured data images are ignored.
- Parses standard `<meta property="og:image" content="...">` tags even when JSON-LD is absent.
- URL references declared as relative paths are resolved against the supplied page URL. This is normal URL resolution of an **explicit reference**, not an image-name guess.
- Only http(s) image references are emitted. Does not validate whether the images remain reachable or whether they are licensed for reuse.
- HTML-only extraction; dynamic JavaScript-generated JSON-LD and image tags may not be present in fetched HTML.
- 15-second network timeout, 2 MB HTML response size limit, same-host redirects only, public network addresses only. No retry storm.
- Do not enter login-only, anti-bot-restricted, or disallowed-to-scrape pages. A 403/404 or timeout results in a readable error dataset item.

### Run locally (Python 3.12+; zero dependencies)

From this Actor folder:

```bash
ACTOR_INPUT_JSON='{"productUrl":"https://www.cancork.com/store/wood-bricks-9mm-cork-wall-panels/"}' python src/main.py
```

The generated local dataset goes into `storage/datasets/default/000000001.json` (and subsequent numbered JSON files). You may also create `storage/key_value_stores/default/INPUT.json`. On Apify, the Actor reads `INPUT` from the run's key-value store by REST and appends records to the default dataset by REST. The platform provides the storage IDs and `APIFY_TOKEN`. No SDK is used.

### Reproduce verification

```bash
python -m unittest discover -s tests -p 'test_*.py' -v
python tests/run_smoke.py
```

`tests/run_smoke.py` launches **`python src/main.py` as a separate process** in a temporary stdlib-only virtual environment and captures the real exit code, stdout, stderr, and saved dataset. The supplied test-only HTTP fixture is substituted using a Python startup hook; the production `src/main.py` is not changed. Thus this is a script-mode test with simulated HTTP, **not a claim of a live Apify run or live website fetch from Python**. See `tests/smoke_evidence.txt` and `tests/smoke_dataset.json`.

### Suggested Apify Store details (not activated)

- Category: **ECOMMERCE** (E-commerce).
- Suggested price: **USD $3 per 1,000 successful image results** ($0.003/result). Do not charge for error/not-found rows when implementing billing.
- `store_metadata.json` contains a **proposal**, not billing configuration.

**Not published; no billing setup or Apify platform run has been performed.**

# Actor input Schema

## `productUrl` (type: `string`):

One publicly reachable HTML page; no login required.

## Actor input object example

```json
{
  "productUrl": "https://woocommerce.com/products/motiv/"
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset containing the Actor's result items

# 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 = {
    "productUrl": "https://woocommerce.com/products/motiv/"
};

// Run the Actor and wait for it to finish
const run = await client.actor("eichan/product-image-gallery-extractor").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 = { "productUrl": "https://woocommerce.com/products/motiv/" }

# Run the Actor and wait for it to finish
run = client.actor("eichan/product-image-gallery-extractor").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 '{
  "productUrl": "https://woocommerce.com/products/motiv/"
}' |
apify call eichan/product-image-gallery-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,eichan/product-image-gallery-extractor"
        }
    }
}
```

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/dFePWqczsVdprWoEO/builds/H3j7vIblv9NNAWqW0/openapi.json
