Product Image URLs Matcher

Match requested SKUs against public JSON or CSV product catalogs and return one validated primary product image URL per match.

This Actor turns a catalog join that is often done manually in spreadsheets into a repeatable product image URLs workflow. It fetches public feeds, finds requested SKUs, selects the first primary image field, follows safe redirects, verifies the final response is an image, and produces one spreadsheet-ready row for every unique requested SKU.

It does not download image files or crawl protected storefront pages.

What this Actor does

1. Downloads up to 10 public JSON or CSV product catalogs.
2. Parses common catalog shapes automatically or follows your field mappings.
3. Matches as many as 10,000 requested SKUs.
4. Selects one main image URL from each matched record.
5. Validates HTTP status, redirects, and image content type.
6. Returns matched, missing, and invalid-image rows in the default dataset.

The first usable catalog match wins. Later catalog URLs act as ordered fallbacks for SKUs absent from earlier feeds.

Who is it for?

• Ecommerce operators preparing marketplace imports
• Merchandising teams auditing product imagery
• Catalog migration teams joining supplier feeds to internal SKUs
• Agencies delivering clean SKU-to-image spreadsheets
• Data engineers enriching PIM, ERP, or warehouse records
• QA teams checking whether primary product image links still resolve

Use Website Image Extractor when you need to discover every image referenced by HTML pages. Use Web Image Downloader when you need the image files themselves rather than URL records.

Why use Product Image URLs Matcher

A plain spreadsheet lookup does not tell you whether an image URL redirects, returns HTML, or is broken. A general web crawler may return logos, thumbnails, gallery images, and secondary views.

This Actor focuses on a narrower result:

• exact SKU join semantics;
• one selected image per match;
• explicit main-image field control;
• no image downloads;
• validation evidence in every matched row;
• diagnostics for missing and invalid records;
• JSON and CSV support in one workflow.

Supported catalog formats

JSON

The Actor accepts a top-level array, one object, or an object containing a conventional array named:

• products
• items
• records
• results
• data

For other shapes, set recordsPath to a dot path such as payload.catalog.products.

CSV

CSV parsing supports quoted fields, commas inside quoted values, UTF-8 byte-order marks, blank lines, and uneven optional columns. The first row must contain column names.

When an image cell contains comma-separated URLs, the first URL is selected as the primary image.

Automatic field detection

If mappings are omitted, the Actor checks common fields.

Purpose	Common fields
SKU	sku, SKU, variantSku, variant_sku, Variant SKU, id
Primary image	mainImageUrl, main_image_url, imageUrl, image_url, image, Images, images, thumbnail
Product name	name, title, Name, Title
Product page	productUrl, product_url, url, permalink, URL

Explicit fields may be dot paths. For example, use variants.primary.sku or media.primary.url.

Getting started

1. Open the Actor input page.
2. Add one or more anonymously reachable catalog URLs.
3. Paste the SKUs you want to match.
4. Leave format and fields on automatic detection for a common feed.
5. Add explicit field paths for a custom schema.
6. Keep Validate image URLs enabled for import-ready evidence.
7. Run the Actor.
8. Export the default dataset as CSV, Excel, JSON, or another supported format.

A small working JSON input:

{
  "catalogUrls": [
    { "url": "https://dummyjson.com/products?limit=100" }
  ],
  "skus": [
    "BEA-ESS-ESS-001",
    "GRO-BRD-CUC-021",
    "KIT-BRD-BOX-051"
  ],
  "validateImages": true
}

Input parameters

Field	Type	Default	Description
catalogUrls	array	required	One to 10 public JSON or CSV URLs
skus	string array	required	One to 10,000 requested SKUs
catalogFormat	string	auto	auto, json, or csv
recordsPath	string	empty	Dot path to a JSON record array
skuField	string	automatic	SKU field name or dot path
imageField	string	automatic	Primary image field name or dot path
productNameField	string	automatic	Optional name field or dot path
productUrlField	string	automatic	Optional product page field or dot path
caseSensitive	boolean	false	Require exact SKU capitalization
validateImages	boolean	true	Require a successful image/* response
validationConcurrency	integer	10	Parallel validators, from 1 to 25

Duplicate requested SKUs are emitted once. Leading and trailing whitespace is removed before matching.

WooCommerce CSV example

The official WooCommerce sample export uses SKU, Name, and Images columns:

{
  "catalogUrls": [
    {
      "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/plugins/woocommerce/sample-data/sample_products.csv"
    }
  ],
  "skus": [
    "woo-vneck-tee",
    "woo-hoodie",
    "woo-cap"
  ],
  "catalogFormat": "csv",
  "skuField": "SKU",
  "imageField": "Images",
  "productNameField": "Name",
  "validateImages": true
}

The Actor uses the first URL in Images, so secondary gallery views are not returned as separate matches.

Multi-catalog fallback workflow

Supply feeds in priority order when different vendors or platforms own different SKUs:

{
  "catalogUrls": [
    { "url": "https://dummyjson.com/products?limit=100" },
    {
      "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/plugins/woocommerce/sample-data/sample_products.csv"
    }
  ],
  "skus": [
    "BEA-ESS-ESS-001",
    "KIT-BRD-BOX-051",
    "woo-vneck-tee",
    "woo-hoodie",
    "missing-example-sku"
  ],
  "validateImages": true,
  "validationConcurrency": 5
}

This is useful for supplier fallback, catalog migrations, and recurring image-link QA.

Output fields

Field	Meaning
sku	Requested normalized SKU
matchedSku	Exact value found in the catalog
status	matched, not_found, or invalid_image
imageUrl	Primary URL selected from the source record
resolvedImageUrl	Final URL after validated redirects
imageContentType	Response media type, such as image/webp
imageHttpStatus	Final validation status code
productName	Optional catalog product name
productUrl	Optional absolute product page URL
catalogUrl	Final catalog URL that supplied the match
catalogFormat	json or csv
validated	Whether this run confirmed a successful image response
error	Concise missing or validation diagnostic
matchedAt	ISO 8601 processing timestamp

Example output

A successful current-format record looks like this:

{
  "sku": "BEA-ESS-ESS-001",
  "matchedSku": "BEA-ESS-ESS-001",
  "status": "matched",
  "imageUrl": "https://cdn.dummyjson.com/product-images/beauty/essence-mascara-lash-princess/1.webp",
  "resolvedImageUrl": "https://cdn.dummyjson.com/product-images/beauty/essence-mascara-lash-princess/1.webp",
  "imageContentType": "image/webp",
  "imageHttpStatus": 200,
  "productName": "Essence Mascara Lash Princess",
  "productUrl": null,
  "catalogUrl": "https://dummyjson.com/products?limit=100",
  "catalogFormat": "json",
  "validated": true,
  "error": null,
  "matchedAt": "2026-01-15T12:00:00.000Z"
}

A missing SKU still gets a dataset row with status: "not_found", null image fields, and a diagnostic. This makes spreadsheet reconciliation straightforward.

Image validation behavior

Validation first sends an HTTP HEAD request. If a server rejects HEAD with 403 or 405, the Actor sends a ranged GET and cancels the body after headers arrive.

A validated match must have:

• a final 2xx status;
• an image/* content type;
• no private or local redirect target;
• no more than five redirects.

The Actor does not store the image file.

Set validateImages to false only when you want fast catalog joining and accept unverified URLs. Such matched rows have validated: false and no observed HTTP metadata.

How much does it cost to match SKUs to product image URLs?

The Actor uses pay-per-event pricing:

• one small start event per run;
• one item event for each SKU that produces a usable primary image URL;
• no item event for not_found or invalid_image rows.

At the current BRONZE rate, a run costs $0.005 to start plus $0.0008096 per validated match. For example:

Validated matches	Estimated BRONZE price
10	0.0131 USD
100	0.0860 USD
700	0.5717 USD

Your active Apify plan tier determines the exact per-item rate shown in Console. Final live rates always appear on the Actor pricing tab before you start a run.

Reliability and retry behavior

Catalog requests retry only transient failures such as timeouts, 429 responses, and temporary 5xx responses. Stable invalid URLs and authorization failures are not retried blindly.

One failed catalog does not discard successful catalogs. The run fails only when no supplied catalog can be fetched and parsed.

Image-level failures produce invalid_image rows instead of failing the entire batch.

Limits and important behavior

• Catalog URLs must be anonymously reachable over HTTP or HTTPS.
• Private, loopback, local-network, credential-bearing, and reserved-address URLs are rejected.
• Each catalog response is limited to 10 MB.
• Up to 10 catalogs and 10,000 SKUs are supported per run.
• SKU matching is case-insensitive by default.
• The first catalog candidate wins for duplicate SKUs.
• The first image in an array or comma-separated field is selected.
• The Actor does not discover product pages from a storefront domain.
• The Actor does not solve logins, CAPTCHAs, or signed private feeds.
• XML and spreadsheet files such as XLSX are not catalog input formats.

Convert an XLSX file to CSV or publish it as an anonymously reachable CSV endpoint before running.

Spreadsheet and data-pipeline integrations

Export the dataset directly from Apify Console as CSV or Excel for a clean SKU-to-URL sheet.

For recurring work, connect the dataset to:

• Google Sheets
• Airtable
• Make
• Zapier
• Keboola
• webhooks
• your PIM or warehouse loader

A common pipeline is:

1. Export SKUs from a PIM.
2. Publish or expose the supplier catalog as JSON/CSV.
3. Run this Actor on a schedule.
4. Filter status = matched for imports.
5. Route not_found and invalid_image rows to a QA queue.
6. Compare resolvedImageUrl values with the previous run.

Run with the Apify API using cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~sku-main-image-url-matcher/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "catalogUrls": [{"url":"https://dummyjson.com/products?limit=100"}],
    "skus": ["BEA-ESS-ESS-001", "GRO-BRD-CUC-021"],
    "validateImages": true
  }'

Use the returned run's defaultDatasetId to download results.

Run with JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor('automation-lab/sku-main-image-url-matcher').call({
  catalogUrls: [{ url: 'https://dummyjson.com/products?limit=100' }],
  skus: ['BEA-ESS-ESS-001', 'GRO-BRD-CUC-021'],
  validateImages: true,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Run with Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("automation-lab/sku-main-image-url-matcher").call(
    run_input={
        "catalogUrls": [
            {"url": "https://dummyjson.com/products?limit=100"}
        ],
        "skus": ["BEA-ESS-ESS-001", "GRO-BRD-CUC-021"],
        "validateImages": True,
    }
)

items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)

Use with Apify MCP

Claude Code setup

Add the Actor to Claude Code:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/sku-main-image-url-matcher"

Claude Desktop setup

Use this JSON configuration in Claude Desktop:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/sku-main-image-url-matcher"
    }
  }
}

Cursor setup

Use the same MCP server URL in Cursor's MCP settings: https://mcp.apify.com?tools=automation-lab/sku-main-image-url-matcher.

VS Code setup

Add the same HTTP MCP server URL to your VS Code MCP configuration and name the server apify.

Example prompts

• “Match these SKUs against this public JSON feed and return only validated image rows.”
• “Check the WooCommerce CSV for these product SKUs and list broken primary images.”
• “Join this SKU batch across both supplier catalogs and summarize missing products.”

Legality and responsible use

Only process catalogs you are authorized to access. Respect feed licenses, website terms, robots guidance where applicable, rate limits, intellectual-property rights, and privacy laws.

Do not use this Actor to bypass authentication or access controls. Public reachability does not automatically grant permission to redistribute catalog data or product images.

The Actor returns URLs and metadata; it does not transfer ownership or usage rights for image content.

Troubleshooting

None of the supplied catalogs could be fetched

Check that every URL is public, anonymously reachable, and returns JSON or CSV rather than an HTML login page. Confirm that the response is under 10 MB.

Every SKU is not_found

Inspect capitalization and whitespace, then set skuField explicitly. For nested JSON, supply a dot path. Set caseSensitive to true only if capitalization differentiates real SKUs.

The JSON feed parsed only one record

Set recordsPath to the array, for example payload.products.

A matched SKU has invalid_image

Read imageHttpStatus, imageContentType, and error. The URL may be broken, redirect to HTML, require authentication, or reject automated validation.

The wrong image was selected

Set imageField to the catalog's canonical primary-image property. Arrays and comma-separated CSV image lists intentionally select their first entry.

Validation is slow

Increase validationConcurrency gradually up to 25. Keep it lower for rate-limited image hosts.

FAQ

Does the Actor download images?

No. It validates headers and cancels fallback response bodies without storing image files.

Does it scrape ecommerce websites by SKU?

No. It joins SKUs against public JSON or CSV catalogs supplied by the user. It does not search arbitrary storefront pages.

Can I provide multiple catalogs?

Yes. Provide up to 10 URLs in priority order. Later feeds fill still-unmatched SKUs.

Are missing SKUs charged as items?

No. They are returned for reconciliation but do not emit the per-match item event.

Can it handle nested fields?

Yes. Use dot paths for recordsPath, skuField, imageField, productNameField, and productUrlField.

Can it return all gallery images?

No. The product contract is exactly one primary URL per matched SKU. Use Website Image Extractor for a broader inventory.

Can it validate redirects?

Yes. It follows up to five public HTTP redirects and records the final URL.

Can I schedule recurring checks?

Yes. Schedule the same input and compare each run's resolvedImageUrl, status, and validation fields in your downstream system.

Related Automation Lab Actors

• Website Image Extractor — discover image references, alt text, and page provenance from HTML.
• Web Image Downloader — download supplied image URLs and return file metadata.
• Structured Data Extractor — extract JSON-LD and other structured data from public pages.

These Actors solve adjacent tasks; they do not replace the SKU-to-catalog matching workflow described here.