# Amazon Brand Price Segments (`practical_ai_lab_jp/pal-amazon-brand-price-segments`) Actor

Turn your authorized Amazon product exports into brand-by-category price segments, seller offer gaps and currency-separated summaries. Useful for recurring assortment and competitor pricing reviews; no scraping or price predictions.

- **URL**: https://apify.com/practical_ai_lab_jp/pal-amazon-brand-price-segments.md
- **Developed by:** [Practical AI Lab](https://apify.com/practical_ai_lab_jp) (community)
- **Categories:** E-commerce, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 segment rows

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

## Amazon Brand Price Segments

Paste product records you already have and get transparent price bands per brand, the bands where a brand has no offers, and separate market splits for each currency. The Actor works only on the data you supply. It does not visit Amazon or any other website, uses no proxies and makes no network requests.

### What you get

For every category and currency combination:

- **`market_split` row**: listing count, min / p25 / median / p75 / max / mean, the exact price range of each band, and bands that hold fewer listings than your minimum group size.
- **`brand_segment` rows**: the same statistics per brand, share of listings, brand median versus market median (percent), how many listings fall in each band, the dominant band, and **offer gap bands** (bands where the market has listings but this brand has none).

Currencies are never mixed or converted. EUR and USD records form separate markets.

### How bands work

Bands are quantile cut points of all supplied prices in one category and currency (for example quartiles when `bandCount` is 4). Cut points equal to the market minimum are dropped, so a market with identical prices has a single band. A price exactly on a cut point belongs to the higher band. Labels are `B1` (lowest) upward.

### Input

| Field | Meaning |
| --- | --- |
| `products` | Array of objects (required). |
| `defaultCurrency` | Used only when a record has no currency. Empty means such records are grouped as `UNKNOWN`. |
| `bandCount` | 2 to 6, default 4. |
| `minGroupSize` | Threshold for low-sample flags, default 3. |
| `maxRecords` | Cap on processed records, default 5000. |
| `includeMarketRows` | Default true. |

Recognised record fields (first non-empty wins): brand (`brand`, `brandName`, `manufacturer`), category (`category`, `categoryName`, `productCategory`, `department`), price (`price`, `currentPrice`, `salePrice`, `offerPrice`; numbers, strings such as `"$1,299.50"` or `"1.299,50 €"`, or `{"value": 12, "currency": "EUR"}`), currency (`currency`, `priceCurrency`, `currencyCode`), identifier (`asin`, `sku`, `productId`). Records with the same identifier, currency and category are de-duplicated (first one kept).

#### Example input

```json
{
    "products": [
        {"asin": "A1", "brand": "Alpha Audio", "category": "Headphones", "price": 24.99, "currency": "USD"},
        {"asin": "A2", "brand": "Alpha Audio", "category": "Headphones", "price": 34.5, "currency": "USD"},
        {"asin": "A3", "brand": "Alpha Audio", "category": "Headphones", "price": 39.0, "currency": "USD"},
        {"asin": "B1", "brand": "Beta Sound", "category": "Headphones", "price": "$59.00", "currency": "USD"},
        {"asin": "B2", "brand": "Beta Sound", "category": "Headphones", "price": "$74.90", "currency": "USD"},
        {"asin": "B3", "brand": "Beta Sound", "category": "Headphones", "price": "$89.00", "currency": "USD"},
        {"asin": "G1", "brand": "Gamma Gear", "category": "Headphones", "price": "29,90 €", "currency": "EUR"}
    ],
    "bandCount": 2,
    "minGroupSize": 3
}
```

The brand and product names above are illustrative placeholders, not real market data.

### Output

Rows go to the default dataset. A `SUMMARY` record in the key-value store lists records received, used, de-duplicated, truncated and skipped (with reasons: `missing_brand`, `invalid_price`, `not_an_object`).

Key fields: `recordType`, `category`, `currency`, `brand`, `listings`, `minPrice`, `p25`, `medianPrice`, `p75`, `maxPrice`, `meanPrice`, `medianVsMarketPct`, `shareOfListingsPct`, `bandCounts`, `dominantBand`, `offerGapBands`, `lowBrandSample`, `thinMarket`, `notes`.

### Limitations and sample-size caveats

- Results describe only the records you provide. An "offer gap" means no supplied listing in that band, not that the real marketplace lacks such offers.
- Small samples are unreliable. Brands with fewer listings than `minGroupSize` are flagged `lowBrandSample`; markets with fewer than two listings per band are flagged `thinMarket`. Quantiles of a handful of prices move a lot when one record changes.
- Prices are taken as given: no fees, shipping, coupons, variants or time-of-capture adjustments. Mixed capture dates distort comparisons.
- Brand names are matched case-insensitively after whitespace cleanup, with no alias merging (for example "Acme" and "Acme Official" stay separate).
- A bare `$` is ambiguous (USD, CAD, AUD and others), so it is not interpreted. Provide a `currency` field or `defaultCurrency`. Thousands/decimal separators in strings are inferred heuristically; use numeric prices when exactness matters.
- Only the first `maxRecords` records are processed.
- No currency conversion, forecasting or demand estimation.

### Pricing

The code defines a `segment-row` charge event, charged once per dataset row after results are stored. Nothing is charged when input is invalid or no row is produced. Pay-per-event pricing is not configured in this repository; any plan is set separately on the platform.

### Local tests

`python -m unittest discover -s tests` runs offline tests of the aggregation logic.

# Actor input Schema

## `products` (type: `array`):

Existing product records you already hold (for example an export from your own research). Each object needs a brand and a price; category, currency and asin are optional. Nothing is fetched from any website.

## `defaultCurrency` (type: `string`):

3-letter code (for example USD) used only when a record has no explicit currency. Leave empty to group such records under UNKNOWN instead of guessing.

## `bandCount` (type: `integer`):

Number of quantile-based price bands (2-6) computed per category and currency.

## `minGroupSize` (type: `integer`):

Brands or bands with fewer listings are flagged as low sample.

## `maxRecords` (type: `integer`):

Only the first N records are processed; the rest are counted as truncated.

## `includeMarketRows` (type: `boolean`):

Add one market_split row per category and currency with band ranges.

## Actor input object example

```json
{
  "products": [
    {
      "asin": "A1",
      "brand": "Alpha Audio",
      "category": "Headphones",
      "price": 24.99,
      "currency": "USD"
    },
    {
      "asin": "A2",
      "brand": "Alpha Audio",
      "category": "Headphones",
      "price": 34.5,
      "currency": "USD"
    },
    {
      "asin": "A3",
      "brand": "Alpha Audio",
      "category": "Headphones",
      "price": 39,
      "currency": "USD"
    },
    {
      "asin": "B1",
      "brand": "Beta Sound",
      "category": "Headphones",
      "price": "$59.00",
      "currency": "USD"
    },
    {
      "asin": "B2",
      "brand": "Beta Sound",
      "category": "Headphones",
      "price": "$74.90",
      "currency": "USD"
    },
    {
      "asin": "B3",
      "brand": "Beta Sound",
      "category": "Headphones",
      "price": "$89.00",
      "currency": "USD"
    },
    {
      "asin": "B4",
      "brand": "Beta Sound",
      "category": "Headphones",
      "price": "$129.00",
      "currency": "USD"
    },
    {
      "asin": "G1",
      "brand": "Gamma Gear",
      "category": "Headphones",
      "price": "29,90 €",
      "currency": "EUR"
    },
    {
      "asin": "G2",
      "brand": "Gamma Gear",
      "category": "Headphones",
      "price": "44,90 €",
      "currency": "EUR"
    },
    {
      "asin": "G3",
      "brand": "Gamma Gear",
      "category": "Headphones",
      "price": "79,00 €",
      "currency": "EUR"
    },
    {
      "asin": "D1",
      "brand": "Delta Desk",
      "category": "Desk Lamps",
      "price": 18,
      "currency": "USD"
    },
    {
      "asin": "D2",
      "brand": "Delta Desk",
      "category": "Desk Lamps",
      "price": 27.5,
      "currency": "USD"
    }
  ],
  "defaultCurrency": "",
  "bandCount": 4,
  "minGroupSize": 3,
  "maxRecords": 5000,
  "includeMarketRows": true
}
```

# Actor output Schema

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

Download rows from the latest run in JSON/CSV.

# 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 = {
    "products": [
        {
            "asin": "A1",
            "brand": "Alpha Audio",
            "category": "Headphones",
            "price": 24.99,
            "currency": "USD"
        },
        {
            "asin": "A2",
            "brand": "Alpha Audio",
            "category": "Headphones",
            "price": 34.5,
            "currency": "USD"
        },
        {
            "asin": "A3",
            "brand": "Alpha Audio",
            "category": "Headphones",
            "price": 39,
            "currency": "USD"
        },
        {
            "asin": "B1",
            "brand": "Beta Sound",
            "category": "Headphones",
            "price": "$59.00",
            "currency": "USD"
        },
        {
            "asin": "B2",
            "brand": "Beta Sound",
            "category": "Headphones",
            "price": "$74.90",
            "currency": "USD"
        },
        {
            "asin": "B3",
            "brand": "Beta Sound",
            "category": "Headphones",
            "price": "$89.00",
            "currency": "USD"
        },
        {
            "asin": "B4",
            "brand": "Beta Sound",
            "category": "Headphones",
            "price": "$129.00",
            "currency": "USD"
        },
        {
            "asin": "G1",
            "brand": "Gamma Gear",
            "category": "Headphones",
            "price": "29,90 €",
            "currency": "EUR"
        },
        {
            "asin": "G2",
            "brand": "Gamma Gear",
            "category": "Headphones",
            "price": "44,90 €",
            "currency": "EUR"
        },
        {
            "asin": "G3",
            "brand": "Gamma Gear",
            "category": "Headphones",
            "price": "79,00 €",
            "currency": "EUR"
        },
        {
            "asin": "D1",
            "brand": "Delta Desk",
            "category": "Desk Lamps",
            "price": 18,
            "currency": "USD"
        },
        {
            "asin": "D2",
            "brand": "Delta Desk",
            "category": "Desk Lamps",
            "price": 27.5,
            "currency": "USD"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("practical_ai_lab_jp/pal-amazon-brand-price-segments").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 = { "products": [
        {
            "asin": "A1",
            "brand": "Alpha Audio",
            "category": "Headphones",
            "price": 24.99,
            "currency": "USD",
        },
        {
            "asin": "A2",
            "brand": "Alpha Audio",
            "category": "Headphones",
            "price": 34.5,
            "currency": "USD",
        },
        {
            "asin": "A3",
            "brand": "Alpha Audio",
            "category": "Headphones",
            "price": 39,
            "currency": "USD",
        },
        {
            "asin": "B1",
            "brand": "Beta Sound",
            "category": "Headphones",
            "price": "$59.00",
            "currency": "USD",
        },
        {
            "asin": "B2",
            "brand": "Beta Sound",
            "category": "Headphones",
            "price": "$74.90",
            "currency": "USD",
        },
        {
            "asin": "B3",
            "brand": "Beta Sound",
            "category": "Headphones",
            "price": "$89.00",
            "currency": "USD",
        },
        {
            "asin": "B4",
            "brand": "Beta Sound",
            "category": "Headphones",
            "price": "$129.00",
            "currency": "USD",
        },
        {
            "asin": "G1",
            "brand": "Gamma Gear",
            "category": "Headphones",
            "price": "29,90 €",
            "currency": "EUR",
        },
        {
            "asin": "G2",
            "brand": "Gamma Gear",
            "category": "Headphones",
            "price": "44,90 €",
            "currency": "EUR",
        },
        {
            "asin": "G3",
            "brand": "Gamma Gear",
            "category": "Headphones",
            "price": "79,00 €",
            "currency": "EUR",
        },
        {
            "asin": "D1",
            "brand": "Delta Desk",
            "category": "Desk Lamps",
            "price": 18,
            "currency": "USD",
        },
        {
            "asin": "D2",
            "brand": "Delta Desk",
            "category": "Desk Lamps",
            "price": 27.5,
            "currency": "USD",
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("practical_ai_lab_jp/pal-amazon-brand-price-segments").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 '{
  "products": [
    {
      "asin": "A1",
      "brand": "Alpha Audio",
      "category": "Headphones",
      "price": 24.99,
      "currency": "USD"
    },
    {
      "asin": "A2",
      "brand": "Alpha Audio",
      "category": "Headphones",
      "price": 34.5,
      "currency": "USD"
    },
    {
      "asin": "A3",
      "brand": "Alpha Audio",
      "category": "Headphones",
      "price": 39,
      "currency": "USD"
    },
    {
      "asin": "B1",
      "brand": "Beta Sound",
      "category": "Headphones",
      "price": "$59.00",
      "currency": "USD"
    },
    {
      "asin": "B2",
      "brand": "Beta Sound",
      "category": "Headphones",
      "price": "$74.90",
      "currency": "USD"
    },
    {
      "asin": "B3",
      "brand": "Beta Sound",
      "category": "Headphones",
      "price": "$89.00",
      "currency": "USD"
    },
    {
      "asin": "B4",
      "brand": "Beta Sound",
      "category": "Headphones",
      "price": "$129.00",
      "currency": "USD"
    },
    {
      "asin": "G1",
      "brand": "Gamma Gear",
      "category": "Headphones",
      "price": "29,90 €",
      "currency": "EUR"
    },
    {
      "asin": "G2",
      "brand": "Gamma Gear",
      "category": "Headphones",
      "price": "44,90 €",
      "currency": "EUR"
    },
    {
      "asin": "G3",
      "brand": "Gamma Gear",
      "category": "Headphones",
      "price": "79,00 €",
      "currency": "EUR"
    },
    {
      "asin": "D1",
      "brand": "Delta Desk",
      "category": "Desk Lamps",
      "price": 18,
      "currency": "USD"
    },
    {
      "asin": "D2",
      "brand": "Delta Desk",
      "category": "Desk Lamps",
      "price": 27.5,
      "currency": "USD"
    }
  ]
}' |
apify call practical_ai_lab_jp/pal-amazon-brand-price-segments --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,practical_ai_lab_jp/pal-amazon-brand-price-segments"
        }
    }
}
```

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/I6txPFM3apbPAQCrQ/builds/h1FhQmowkSSckAqlu/openapi.json