# Amazon Product Details Agent (`buzzidata/amazon-product-details-agent`) Actor

Turn Amazon ASINs or product URLs into structured product data for Amazon.com, Amazon.co.uk, and Amazon.de. Title, brand, BSR, ratings, images, prices, and variants. Only successful checks are billed.

- **URL**: https://apify.com/buzzidata/amazon-product-details-agent.md
- **Developed by:** [Buzzi Data](https://apify.com/buzzidata) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 product checks

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?

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

## Amazon Product Details Agent

Turn Amazon ASINs or product URLs into structured product data for [Amazon.com](https://www.amazon.com), [Amazon.co.uk](https://www.amazon.co.uk), and [Amazon.de](https://www.amazon.de). Each successful check returns title, brand, images, ratings, Best Sellers Rank, availability, prices, and variants as clean JSON for catalogs, research, and agent tools.

Failed checks are written with a typed error (`BLOCKED`, `RATE_LIMIT`, `PARSE`, `NETWORK`, `NOT_FOUND`) and are **never billed**. Only successful checks are charged.

Published by **buzzidata**. For live Buy Box winners and competing landed-cost offers, use the sister Actor [Amazon Buy Box + Offers Agent](https://apify.com/buzzidata/amazon-buybox-offers-agent).

### Why use Amazon Product Details Agent?

- **Structured agent JSON.** One camelCase record per marketplace and ASIN, ready for MCP clients, catalogs, and downstream tools.
- **Unblocker by default.** Production runs use Apify Unblocker, so typical Amazon.com pages do not need a browser crawler.
- **Billed only when the check succeeds.** The `product_check` event fires only when a row has `ok: true` and `dryRun` is false.
- **Typed errors you can retry.** Retry `BLOCKED` or `RATE_LIMIT` without paying for those attempts.
- **US, UK, and DE storefronts.** Amazon.com, Amazon.co.uk, and Amazon.de from a single Actor.
- **No invented fields.** If title cannot be parsed, the row is `ok: false`. Missing values are `null` or empty arrays.

Use it for:

- **Catalog enrichment.** Populate title, brand, images, bullets, and attribute tables from ASINs or URLs.
- **MAP and offer research.** Snapshot current price, list price, availability, and parent or variation identifiers.
- **Price and availability snapshots.** Capture timestamped price and availability text for monitoring or historical comparison.
- **Agent tool calls.** Return one product record per ASIN for automated workflows.

Apify scheduling, the HTTP API, integrations, proxy rotation, and run monitoring are included. You do not need to operate your own crawler fleet.

### What data can Amazon Product Details Agent extract?

| Field | Type | Description |
| --- | --- | --- |
| `ok` | boolean | `true` only when the product snapshot parsed |
| `asin`, `marketplace`, `url` | string | Identity of the check |
| `title`, `brand` | string | null | Product facts |
| `image`, `images` | string / string\[] | Primary image plus extra gallery URLs |
| `rating`, `reviewCount` | number | null | Stars (0-5) and public rating count |
| `bsr` | `{ rank, category }[]` | Best Sellers Rank rows when Amazon shows them |
| `availabilityText`, `inStock` | string / boolean | null | Visible ship copy and a stock heuristic |
| `price`, `listPrice` | `{ value, currency, raw }` | null | Current and struck-through list price |
| `parentAsin`, `variationAsins` | string / string\[] | Parent and sibling ASINs when present on the page |
| `bulletPoints`, `keyAttributes` | string\[] / `{ name, value }[]` | Feature bullets and overview table |
| `postalCode`, `scrapedAt` | string | Deliver-to ZIP used for the check, ISO timestamp |
| `error`, `errorDescription` | string | null | Typed failure. `null` on success |

You can download the dataset as JSON, HTML, CSV, or Excel.

### How much does it cost?

You are billed **$0.02** per successful product check. The Store event `product_check` is charged only when a snapshot has `ok: true`. Failed checks, `dryRun: true` runs, and invalid input that never became a snapshot are not billed.

| Event | When it fires | When it does not fire |
| --- | --- | --- |
| `product_check` | After a snapshot with `ok: true` is pushed | `ok: false` errors, `dryRun: true`, invalid input that never became a snapshot |
| `apify-actor-start` | Platform start event (if enabled on the Actor) | n/a |

The Actor keeps concurrency at 1 and defaults to Unblocker.

Set `dryRun: true` to parse and write dataset items without billing.

### How to run

1. Open the Actor in Apify Console and go to the **Input** tab.
2. Paste one or more 10-character ASINs, or Amazon `/dp/` URLs.
3. Pick marketplace `com`, `co.uk`, or `de`. Leave `postalCode` at **92618** for US ship context unless you need another ZIP. **92618** is Irvine, CA, used as the example deliver-to ZIP.
4. Keep `proxyGroup` on **UNBLOCKER** unless you need sticky residential IPs.
5. Set `dryRun: true` for a free parse test. Turn it off when you want billed `product_check` runs.
6. Run the Actor. Read items from the default dataset or the API tab.

#### Sample input

```json
{
    "asins": ["B014I8SSD0", "B00MNV8E0C"],
    "productUrls": ["https://www.amazon.com/dp/B014I8SSD0"],
    "marketplace": "com",
    "postalCode": "92618",
    "proxyGroup": "UNBLOCKER",
    "dryRun": true
}
```

See the Input tab for full configuration options.

#### Sample output

```json
{
    "ok": true,
    "asin": "B014I8SSD0",
    "parentAsin": "B00PARENT1",
    "variationAsins": ["B00VARRED1", "B00VARBLU1"],
    "marketplace": "com",
    "url": "https://www.amazon.com/dp/B014I8SSD0",
    "title": "YETI Rambler 20 oz Tumbler, Stainless Steel, Vacuum Insulated with MagSlider Lid",
    "brand": "YETI",
    "image": "https://m.media-amazon.com/images/I/71exampleMAIN.jpg",
    "rating": 4.8,
    "reviewCount": 12845,
    "bsr": [{ "rank": 1234, "category": "Kitchen & Dining" }],
    "availabilityText": "In Stock",
    "inStock": true,
    "price": { "value": 35, "currency": "USD", "raw": "$35.00" },
    "listPrice": { "value": 39.99, "currency": "USD", "raw": "$39.99" },
    "bulletPoints": ["18/8 stainless steel construction keeps drinks cold or hot."],
    "keyAttributes": [{ "name": "Color", "value": "Black" }],
    "postalCode": "92618",
    "error": null
}
```

#### Deliver-to postal code

Amazon availability and price are location specific. If deliver-to is unset, the HTML often still has title and brand, but availability can read as if the item cannot ship to the selected location. This Actor sets Amazon deliver-to to the given postal code before fetching product pages.

Default **92618** is Irvine, CA, the example US deliver-to ZIP. Use a local postcode for `co.uk` or `de`.

#### Proxy settings

Amazon.com blocks datacenter and AUTO Apify Proxy groups. **Unblocker is the recommended Amazon.com production default.** Residential US is a fallback when you need sticky IPs for deliver-to cookies, or when the account has no Unblocker units.

`proxyGroup` defaults to `UNBLOCKER`. To use sticky residential IPs instead:

```json
{ "asins": ["B014I8SSD0"], "proxyGroup": "RESIDENTIAL", "dryRun": true }
```

This Actor parses product HTML over HTTP. A full browser is not required for typical product pages.

### Input

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `asins` | `string[]` | (none) | 10-character ASINs |
| `productUrls` | `string[]` | (none) | Amazon URLs. ASIN extracted from `/dp/` and related paths |
| `marketplace` | `com` | `co.uk` | `de` | `com` | Primary storefront for bare ASINs |
| `postalCode` | string | `92618` | Deliver-to ZIP / postal code. Alias: `zipCode` |
| `proxyGroup` | `UNBLOCKER` | `RESIDENTIAL` | `UNBLOCKER` | Production default. Select `RESIDENTIAL` as a sticky-IP fallback |
| `proxyCountry` | `US` | `GB` | `DE` | `US` | Used when the group is residential. Ignored for Unblocker |
| `dryRun` | boolean | `false` | Write items, do not charge |
| `proxyConfiguration` | proxy | widget RESIDENTIAL + US | Optional Console widget. Real default is `proxyGroup=UNBLOCKER`, which overrides this |

At least one parseable ASIN (from `asins` or `productUrls`) is required. A URL on amazon.co.uk or amazon.de overrides `marketplace` for that item.

### Output

Each dataset item is one marketplace x ASIN check. Successful rows have `ok: true`, product fields, and `error: null`. Failed rows have `ok: false` plus a typed `error` and `errorDescription`. Download JSON, HTML, CSV, or Excel from the run's dataset, or read items from the API.

#### Error codes

| Code | Meaning |
| --- | --- |
| `BLOCKED` | CAPTCHA, robot check, or automated-access interstitial |
| `RATE_LIMIT` | HTTP 429/503 or throttle copy |
| `PARSE` | HTML loaded but title could not be extracted |
| `NETWORK` | Timeouts, DNS, connection errors, other 4xx/5xx |
| `NOT_FOUND` | Amazon page-not-found |

The Actor rotates the session on CAPTCHA and throttle (up to 6 request retries / 8 session uses) before writing `BLOCKED` or `RATE_LIMIT`.

### MCP / agent tips

Each dataset item is a JSON object with `ok`, typed `error`, and product fields. Point an MCP client at the default dataset (`{{links.apiDefaultDatasetUrl}}/items`) or run the Actor via the Apify MCP server. Failed checks remain in the dataset so an agent can retry only `BLOCKED` / `RATE_LIMIT` without being billed for those attempts.

### Risks and limitations

- **Amazon ToS.** Scraping Amazon storefronts may violate Amazon's terms. Use this Actor only where you have a lawful basis. This is not an official Amazon API.
- **Blocking.** Datacenter IPs often return CAPTCHAs. This Actor defaults to Apify Unblocker (residential is a fallback) and retries CAPTCHA and throttle pages with a new session.
- **Late-loading layouts.** Some product pages load title or price after the initial HTML. Those checks can return `PARSE`.
- **Page markup changes.** Amazon A/B-tests title, price, and BSR markup. Field coverage can change when Amazon changes the page.
- **Stock is heuristic.** `inStock` is derived from availability copy, not warehouse quantity.

This Actor does not scrape reviews, search results, or seller private data.

### FAQ, disclaimers, and support

**Does this Actor invent product data?** No. Missing fields are `null` or empty arrays. `ok` is true only when a title was parsed.

**Why was I not charged for a row?** `product_check` is skipped when `ok` is false or `dryRun` is true.

**Which marketplaces are supported?** Amazon.com, Amazon.co.uk, and Amazon.de.

Our Actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly on Amazon product pages. We therefore believe that our Actors, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by the GDPR in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you are unsure whether your reason is legitimate, consult your lawyers.

Use the **Issues** tab for feedback. Use the **API** tab for programmatic access.

### Related Actors

Need the live Buy Box winner and competing landed-cost offers for the same ASINs? Use [Amazon Buy Box + Offers Agent](https://apify.com/buzzidata/amazon-buybox-offers-agent).

### License

Apache-2.0

# Actor input Schema

## `asins` (type: `array`):

Amazon ASINs to check (10-character identifiers). Duplicate ASINs are fetched once per marketplace.

## `productUrls` (type: `array`):

Amazon product URLs. The Actor extracts the ASIN from /dp/, /gp/product/, /gp/aw/d/, or an asin= query parameter. A URL on amazon.co.uk or amazon.de overrides the marketplace field for that item.

## `marketplace` (type: `string`):

Primary Amazon marketplace for ASINs that do not already include a storefront in the URL.

## `postalCode` (type: `string`):

Deliver-to postal code for availability and shipping context. Default 92618 is Irvine, CA, used as the example US ZIP. Accepts US ZIP codes (for example 92618) and UK or DE postcodes. In JSON input, zipCode is treated the same as postalCode.

## `dryRun` (type: `boolean`):

Parse and write dataset items without charging for successful product checks. Use this to test parsing before you run billed checks.

## `proxyGroup` (type: `string`):

Apify Proxy product to use. UNBLOCKER is the recommended production default for Amazon.com. Choose RESIDENTIAL when you need a sticky IP so deliver-to location stays set. Unblocker is billed in Unblocker units. Residential is billed per GB.

## `proxyCountry` (type: `string`):

Proxy country when proxyGroup is RESIDENTIAL. Amazon.com requires US residential IPs. Default US. Ignored for UNBLOCKER, because country targeting shrinks the bypass pool.

## `proxyConfiguration` (type: `object`):

Optional proxy widget. The production default is proxyGroup=UNBLOCKER, which overrides this widget. Pick RESIDENTIAL on proxyGroup as a sticky-IP fallback. Datacenter and AUTO IPs are frequently blocked. Set useApifyProxy=false only for local debugging.

## Actor input object example

```json
{
  "asins": [
    "B014I8SSD0",
    "B00MNV8E0C"
  ],
  "productUrls": [
    "https://www.amazon.com/dp/B014I8SSD0"
  ],
  "marketplace": "com",
  "postalCode": "92618",
  "dryRun": false,
  "proxyGroup": "UNBLOCKER",
  "proxyCountry": "US",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "asins": [
        "B014I8SSD0",
        "B00MNV8E0C"
    ],
    "productUrls": [
        "https://www.amazon.com/dp/B014I8SSD0"
    ],
    "postalCode": "92618",
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("buzzidata/amazon-product-details-agent").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 = {
    "asins": [
        "B014I8SSD0",
        "B00MNV8E0C",
    ],
    "productUrls": ["https://www.amazon.com/dp/B014I8SSD0"],
    "postalCode": "92618",
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("buzzidata/amazon-product-details-agent").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 '{
  "asins": [
    "B014I8SSD0",
    "B00MNV8E0C"
  ],
  "productUrls": [
    "https://www.amazon.com/dp/B014I8SSD0"
  ],
  "postalCode": "92618",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call buzzidata/amazon-product-details-agent --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,buzzidata/amazon-product-details-agent"
        }
    }
}

```

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/Ux4w3b6yh57NhWLme/builds/uofRCfiOwJ0hhGDeL/openapi.json