# Marketplace Trending Radar (`apt_marble/marketplace-trending-radar`) Actor

Track what is rising for any product search term across Amazon, eBay, Walmart, AliExpress, Alibaba and Taobao: rerun the same terms over time and get every product marked new, rising, falling or steady, with a 0-100 trend score, rank changes and a cross-marketplace breakout flag.

- **URL**: https://apify.com/apt_marble/marketplace-trending-radar.md
- **Developed by:** [Hamza](https://apify.com/apt_marble) (community)
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.20 / 1,000 result 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

## Marketplace Trending Radar

What is rising right now — and what just appeared? Track any product search
term across **Amazon, eBay, Walmart, AliExpress, Alibaba and Taobao**: each
run reads the current top products for your terms and compares them against
the previous snapshot, so every product comes back marked **new**, **rising**,
**falling** or **steady**, with a 0-100 **trend score** and a
**cross-marketplace breakout flag** when the same product surfaces on several
marketplaces at once. No account and no login are needed: type your terms,
press start, and rerun whenever you want a fresh read — the second run is
where the trends appear. Pages are read directly, with no browser and nothing
to sign in to.

### What you can do with it

- **Catch breakouts early.** Products that appear on several marketplaces at
  the same time are flagged `crossMarketplace` — the strongest early signal
  that a product is taking off.
- **See movement, not just a snapshot.** Rerun the same terms daily or
  weekly: every product is compared against the previous run and marked with
  its rank change and direction.
- **Spot new arrivals.** Products that were not in the previous snapshot are
  marked `newThisRun` with their first-seen date.
- **Rank by momentum.** The 0-100 trend score blends rank position, the
  marketplace's own demand signals (sold units, ratings), newness and
  cross-marketplace presence, so the hottest products sort to the top.
- **Feed a spreadsheet or a schedule.** Every field is a plain column —
  export to Excel, Google Sheets, CSV or JSON, or put the actor on a schedule
  and watch trends build up.

### What you get

One row per product per marketplace per search term. Abridged real example:

```json
{
  "keyword": "wireless earbuds",
  "marketplace": "aliexpress",
  "rank": 3,
  "title": "TWS Wireless Bluetooth Headset ...",
  "price": 0.33,
  "currency": "USD",
  "soldCount": 45210,
  "trendScore": 87,
  "direction": "new",
  "newThisRun": true,
  "rankChange": null,
  "crossMarketplace": true,
  "matchedOn": ["alibaba", "taobao"],
  "url": "https://www.aliexpress.com/item/3256807042125723.html"
}
```

### How the trend signals work

- **Snapshots live in a key-value store** named `trend-radar-state`, kept per
  **tracking scope**. Rerun with the same scope and terms and every product
  is compared against the previous snapshot: `direction` is `new`, `rising`,
  `falling` or `steady`, and `rankChange` shows how many places it moved.
  Use a different scope per project or client so trackings never mix.
- **The first run is the baseline.** Everything is marked `new`; from the
  second run on, movement is real.
- **Trend score (0-100)** blends four parts: position near the top of the
  site's own best-selling ordering, the raw demand signal (sold units or
  ratings), a boost for being new this run, and a boost for appearing on
  several marketplaces at once.
- **Cross-marketplace matching** compares product titles across marketplaces
  within the same search term and flags likely matches.

### Input

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| **Search terms to track** | list | `wireless earbuds` | Up to 20 terms per run. Taobao reads work best with Chinese terms. |
| **Marketplaces** | multi-select | all six | Where to track the terms. |
| **Products to track per marketplace** | number | 30 | How many top products are compared run by run. |
| **Tracking scope** | string | `default` | Snapshots are kept per scope; rerunning the same scope is what makes trends appear. |
| **Parallel reads** | number | 4 | How many marketplace reads run at once. |

### Good to know

- **Partial runs still deliver.** A marketplace that cannot be read is marked
  `error` with the reason; everything else is tracked normally.
- **Taobao speaks Chinese.** Its catalogue only lists terms from its own
  vocabulary; other terms return an explanatory note instead of fake numbers.
- **Snapshots persist between runs** of the same actor, so schedules and
  manual reruns build one continuous trend history per scope.

# Actor input Schema

## `keywords` (type: `array`):

One or more product searches, exactly as you would type them into a marketplace search box. Each term is tracked on every selected marketplace and compared against the previous run. Up to 20 per run.

## `marketplaces` (type: `array`):

Which marketplaces to track. All six are tracked by default.

## `maxProductsPerMarketplace` (type: `integer`):

How many top products to read on each marketplace for each term. These are compared against the previous snapshot run by run.

## `stateScope` (type: `string`):

Snapshots are kept per scope. Use one scope per project or client so different trackings never mix. Rerunning the same scope is what makes products rise, fall or appear new.

## `maxConcurrency` (type: `integer`):

How many marketplace reads to run at the same time. Higher is faster.

## Actor input object example

```json
{
  "keywords": [
    "wireless earbuds"
  ],
  "marketplaces": [
    "amazon",
    "ebay",
    "walmart",
    "aliexpress",
    "alibaba",
    "taobao"
  ],
  "maxProductsPerMarketplace": 30,
  "stateScope": "default",
  "maxConcurrency": 4
}
```

# Actor output Schema

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

One trend-product row per product per marketplace per search term.

# 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 = {
    "keywords": [
        "wireless earbuds"
    ],
    "marketplaces": [
        "amazon",
        "ebay",
        "walmart",
        "aliexpress",
        "alibaba",
        "taobao"
    ],
    "maxProductsPerMarketplace": 30,
    "stateScope": "default",
    "maxConcurrency": 4
};

// Run the Actor and wait for it to finish
const run = await client.actor("apt_marble/marketplace-trending-radar").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 = {
    "keywords": ["wireless earbuds"],
    "marketplaces": [
        "amazon",
        "ebay",
        "walmart",
        "aliexpress",
        "alibaba",
        "taobao",
    ],
    "maxProductsPerMarketplace": 30,
    "stateScope": "default",
    "maxConcurrency": 4,
}

# Run the Actor and wait for it to finish
run = client.actor("apt_marble/marketplace-trending-radar").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 '{
  "keywords": [
    "wireless earbuds"
  ],
  "marketplaces": [
    "amazon",
    "ebay",
    "walmart",
    "aliexpress",
    "alibaba",
    "taobao"
  ],
  "maxProductsPerMarketplace": 30,
  "stateScope": "default",
  "maxConcurrency": 4
}' |
apify call apt_marble/marketplace-trending-radar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apt_marble/marketplace-trending-radar"
        }
    }
}
```

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/3lvuHQ3G8DFL9t3Wq/builds/edSsq6FANRD9kFm3H/openapi.json