# UPCItemDB Barcode Lookup Scraper (`crawlerbros/upcitemdb-barcode-lookup-scraper`) Actor

Look up product data from any UPC, EAN, GTIN or ISBN barcode, or run free-text product search - via the public UPCItemDB catalog. Returns titles, brands, categories, pricing history, images and live merchant offers.

- **URL**: https://apify.com/crawlerbros/upcitemdb-barcode-lookup-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** E-commerce, Developer tools, Automation
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

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

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## UPCItemDB Barcode Lookup Scraper

Look up any product by its barcode — UPC-A, UPC-E, EAN-8, EAN-13, GTIN-14, ISBN-10 or ISBN-13 — or run a free-text product search, using the public [UPCItemDB](https://www.upcitemdb.com/) catalog. Get back product titles, brands, categories, dimensions, weight, historical pricing, images and live merchant offers. No API key, no cookies, no login required.

### What this actor does

- **Barcode lookup** — paste one or many UPC/EAN/GTIN/ISBN codes and get full product details for each, in a single call
- **Keyword search** — search by product name, brand or description across UPCItemDB's catalog
- **Brand, category, title & model filters** — narrow search results to a specific brand, product-category path, title keyword or model number
- **Match mode** — choose between UPCItemDB's best-match (fuzzy) or strict (all-keywords) search matching
- **Automatic pagination** — the actor pages through search results until your `maxItems` cap is reached
- **Merchant offers** — every product includes live pricing from the retailers currently listing it, with shipping, condition and availability
- **Clean, omit-empty output** — fields that UPCItemDB has no data for (including its own literal `N/A` placeholders) are dropped rather than shipped as noise

### Output per product

| Field | Description |
|---|---|
| `upc` | The canonical UPC/EAN code UPCItemDB has on file |
| `ean` | EAN-13 form of the code (zero-padded) |
| `isbn` | ISBN of the title, for books |
| `barcodeType` | Detected barcode family: `UPC-A`, `UPC-E`, `EAN-8`, `EAN-13`, `GTIN-14`, `ISBN-10` or `ISBN-13` |
| `title` | Product title |
| `description` | Full product description |
| `brand` | Brand / manufacturer name |
| `publisher` | Publisher name, for books |
| `model` | Model number / name |
| `color`, `size` | Variant attributes, when available |
| `dimension`, `weight` | Physical dimensions and shipping weight |
| `category` | Full category path, e.g. `Food, Beverages & Tobacco > Beverages > Soda` |
| `currency` | Currency code associated with recorded pricing |
| `lowestRecordedPrice`, `highestRecordedPrice` | Historical price range UPCItemDB has recorded for this product |
| `images[]`, `primaryImage`, `imageCount` | Product images gathered from listing merchants |
| `offers[]` | Current merchant offers — see below |
| `offerCount` | Number of offers returned |
| `asin` | Amazon ASIN, when matched |
| `ebayListingId` | eBay listing ID, when matched |
| `sourceUrl` | Canonical UPCItemDB product page |
| `searchQuery` | The query that matched this product (mode=search only) |
| `matchedBarcode` | The barcode you supplied that resolved this product (mode=lookup only) |
| `recordType` | Always `product` |
| `scrapedAt` | UTC timestamp of when the actor fetched this record |

#### Offer object fields (`offers[]`)

| Field | Description |
|---|---|
| `merchant` | Retailer name |
| `domain` | Retailer domain |
| `title` | The product title as listed by this merchant |
| `currency` | Offer currency, when specified |
| `listPrice` | Original / list price, when discounted |
| `price` | Current selling price |
| `shipping` | Shipping terms |
| `condition` | `New`, `Used`, `Refurbished`, etc. |
| `availability` | Stock status, when reported |
| `offerUrl` | Link to the merchant listing |
| `updatedAt` | When this offer price was last recorded |

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | select | `lookup` | `lookup` (by barcode) or `search` (free-text) |
| `barcodes` | string | `012345678905` | Barcodes to look up (mode=lookup). Separate multiple codes with commas, spaces or new lines |
| `searchQuery` | string | `diet coke` | Free-text search phrase (mode=search) |
| `brand` | string | – | Optional brand filter (mode=search) |
| `category` | string | – | Optional category filter (mode=search) |
| `titleFilter` | string | – | Optional title-keyword filter (mode=search) |
| `model` | string | – | Optional model-number filter (mode=search) |
| `matchMode` | select | `best` | `best` (fuzzy match) or `strict` (all keywords must match), mode=search |
| `maxItems` | integer | `20` | Cap on emitted product records (1–200) |

#### Example: look up multiple barcodes at once

```json
{
  "mode": "lookup",
  "barcodes": "012345678905, 049000028911, 9780261103573"
}
```

#### Example: search with brand + category filters

```json
{
  "mode": "search",
  "searchQuery": "shave cream",
  "brand": "Kyoku",
  "category": "Health & Beauty",
  "maxItems": 30
}
```

#### Example: search with title + model filters and strict matching

```json
{
  "mode": "search",
  "searchQuery": "iphone 6",
  "titleFilter": "64gb",
  "model": "MG5A2LL",
  "matchMode": "strict",
  "maxItems": 20
}
```

#### Example: plain keyword search

```json
{
  "mode": "search",
  "searchQuery": "wireless mouse",
  "maxItems": 50
}
```

### Use cases

- **Retail & inventory systems** — resolve barcode scans to full product metadata in bulk
- **Price monitoring** — pull current merchant offers and historical price ranges for a product catalog
- **Catalog enrichment** — backfill missing titles, images, categories and dimensions from a UPC/EAN list
- **Competitive research** — search a category or brand to see which merchants are actively selling it and at what price
- **E-commerce onboarding** — auto-fill new listings from a supplier's barcode list
- **Data validation** — confirm a barcode is registered and see what product it's mapped to before shipping inventory

### FAQ

**What barcode types are supported?** UPC-A (12 digits), UPC-E (6–8 digits), EAN-8, EAN-13, GTIN-14, and book ISBNs (ISBN-10 and ISBN-13). Dashes and spaces in the barcode are stripped automatically.

**Can I look up more than one barcode per run?** Yes — separate barcodes with commas, spaces or new lines in the `barcodes` field. UPCItemDB's public trial endpoint only resolves 2 codes per underlying API call, so the actor automatically batches your list into chunks of 2 (with a short pause between chunks) until every barcode has been looked up or `maxItems` is reached.

**Why do some products have no `brand`, `color` or `size`?** UPCItemDB only returns fields it actually has data for. When the upstream catalog literally reports `N/A` or `unknown` for a field, the actor treats that as "no data" and omits the field rather than shipping a placeholder.

**Why is `lowestRecordedPrice` sometimes missing?** UPCItemDB records this as `0` when it has no confirmed historical low price. The actor omits `0`-valued price fields since they represent "no data," not a genuine free price.

**Does the search support pagination?** Yes — the actor automatically pages through search results (in batches of a few products per request) until it reaches your `maxItems` cap or runs out of matches.

**How do brand, category, title and model filters work in search mode?** All four are passed to UPCItemDB's search as narrowing filters and are also re-checked against each result's `brand`/`category`/`title`/`model` fields (case-insensitive substring match) before the record is emitted.

**What does `matchMode` do?** `best` (the default) asks UPCItemDB to return its closest matches even when no single result matches every keyword in your query. `strict` requires every keyword in `searchQuery` to match.

**Is there a rate limit?** Yes, the public UPCItemDB endpoint used by this actor is rate-limited. If the quota is exhausted mid-run after some products have already been emitted, the actor stops cleanly and its status message reports exactly how many products it emitted and that the run was cut short by the quota — it never fabricates placeholder records to make up the difference.

**Why does my search query return 0 results even though the product exists?** UPCItemDB's public `search` endpoint only searches a small curated demo subset of its catalog (mostly common grocery/consumer items), not the full database — this is a limitation of their free trial tier, and returning 0 for an unindexed query is UPCItemDB's genuine answer, not a failed request. `mode=lookup` by exact barcode always checks the full database and is unaffected.

**How fresh is the data?** UPCItemDB continuously crawls merchant catalogs, so pricing, offers and images reflect what merchants were reporting at the time the product was last indexed.

**Is this affiliated with UPCItemDB?** No, this is a third-party actor using the public UPCItemDB API/website.

### Limitations

- **`offerUrl` reliability** — `sourceUrl` (the canonical UPCItemDB product page) and `images[]` are consistently reachable from any client. `offerUrl` is UPCItemDB's own affiliate-tracking redirect link, which chains through third-party affiliate networks to the merchant's page. Some merchant destinations enforce referer/session checks that reject a bare programmatic request even though the same link resolves normally when opened in a browser. Use `offerUrl` as a reference/attribution link rather than a guaranteed-200 deep link.
- **`mode=search` covers a limited demo catalog, not UPCItemDB's full database** — UPCItemDB's free public `search` endpoint only indexes a small curated sample of products (well-known grocery/consumer items like `diet coke`, `milk`, `banana`, `cereal`) rather than their complete catalog. Many everyday queries (e.g. `laptop`, `headphones`, `batteries`) will genuinely return 0 results — this is an upstream trial-tier restriction, not an actor bug. `mode=lookup` by exact barcode is not affected and resolves against the full database.

# Actor input Schema

## `mode` (type: `string`):

What to fetch.

## `barcodes` (type: `string`):

One or more barcodes to look up: UPC-A, UPC-E, EAN-8, EAN-13, GTIN-14, ISBN-10 or ISBN-13. Separate multiple codes with commas, spaces or new lines, e.g. `012345678905, 049000028911`.

## `searchQuery` (type: `string`):

Free-text keyword, brand or product-title search, e.g. `diet coke` or `wireless mouse`. Note: UPCItemDB's public search endpoint only indexes a small curated demo subset of its catalog (mostly common grocery/consumer items) rather than the full database, so uncommon queries may genuinely return 0 results — use mode=lookup with an exact barcode for full-database coverage.

## `brand` (type: `string`):

Narrow search results to a specific brand name, e.g. `Nike`, `Diet Coke`, `Samsung`. Leave empty to search all brands.

## `category` (type: `string`):

Narrow search results to a product category path, e.g. `Health & Beauty`, `Electronics`, `Food, Beverages & Tobacco`. Leave empty to search all categories.

## `titleFilter` (type: `string`):

Narrow search results to a keyword that must appear in the product title, e.g. `64gb` or `2 pack`. Leave empty to skip this filter.

## `model` (type: `string`):

Narrow search results to a specific model number, e.g. `MG5A2LL`. Leave empty to skip this filter.

## `matchMode` (type: `string`):

How UPCItemDB matches your search query against its catalog.

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

Hard cap on emitted product records. In search mode the actor pages through results (~5 products per page) until this cap or the end of results is reached.

## Actor input object example

```json
{
  "mode": "lookup",
  "barcodes": "012345678905",
  "searchQuery": "diet coke",
  "matchMode": "best",
  "maxItems": 20
}
```

# Actor output Schema

## `products` (type: `string`):

Dataset containing all scraped products.

# 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 = {
    "mode": "lookup",
    "barcodes": "012345678905",
    "searchQuery": "diet coke",
    "matchMode": "best",
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/upcitemdb-barcode-lookup-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 = {
    "mode": "lookup",
    "barcodes": "012345678905",
    "searchQuery": "diet coke",
    "matchMode": "best",
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/upcitemdb-barcode-lookup-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 '{
  "mode": "lookup",
  "barcodes": "012345678905",
  "searchQuery": "diet coke",
  "matchMode": "best",
  "maxItems": 20
}' |
apify call crawlerbros/upcitemdb-barcode-lookup-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawlerbros/upcitemdb-barcode-lookup-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/U7lC7KbYSCgiOOoHG/builds/p6Kssf2pPtNpN9iMC/openapi.json