# Xiaohongshu Topic Semantic & Content Opportunity Radar (`scrupulous_buckler/xiaohongshu-topic-semantic-content-opportunity-radar`) Actor

Turn RedNote topic searches into related terms, semantic clusters, trend velocity, brand penetration, top and latest content, and evidence-linked content whitespace.

- **URL**: https://apify.com/scrupulous\_buckler/xiaohongshu-topic-semantic-content-opportunity-radar.md
- **Developed by:** [Peng Lyu](https://apify.com/scrupulous_buckler) (community)
- **Categories:** Social media, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.99 / up to 5 topics and 100 posts

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/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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use 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

## Xiaohongshu Topic Semantic & Content Opportunity Radar

Turn Xiaohongshu / RedNote topic searches into a decision-ready map of related terms, semantic themes, trend velocity, brand penetration, top and latest content, and evidence-linked content whitespace.

This Actor is an independent, unofficial research tool and is not affiliated with Xiaohongshu or RedNote.

### What one report answers

- Which related terms and hashtags surround the seed topics?
- Which decision, concern, review, tutorial, scenario, specification, price, and recommendation clusters dominate?
- Which terms and clusters are new, accelerating, stable, or declining versus the previous comparable snapshot?
- How deeply do tracked brands penetrate posts and engagement?
- Which posts are the most engaging, and which are the newest?
- Which angles combine high sampled demand, lower relative supply, and positive momentum?

### Content opportunity logic

The opportunity score combines three separately visible inputs:

- Demand: average sampled engagement
- Supply gap: relative scarcity within the analyzed sample
- Momentum: observed post-count growth versus a previous comparable snapshot

Each opportunity includes score components, sample confidence, evidence post IDs, and a plain-language explanation. Low-sample confidence reduces the final score, and overlapping terms supported by the same posts are consolidated. A single high-engagement post cannot be presented as a high-confidence trend.

### Data modes

#### No-Cookie demo

Run the default input to see related terms, semantic clusters, brand penetration, trend signals, top/latest content, and whitespace ranking across four sample sunscreen topics.

#### Uploaded notes

Choose `uploadedNotes` and provide a current post sample. Common flat and nested `note_card` field names are normalized automatically. Add `previousNotes` for immediate growth calculations. This mode requires no Cookie and accepts compatible exports from other Xiaohongshu Actors.

#### Live topic search

Choose `liveSearch`, enter one to five seed topics, and provide your own Xiaohongshu session Cookie in the secret input. The Cookie is never written to output or logs.

Authenticated search can be affected by account state, session expiry, region, rate limits, ranking changes, and platform updates. Use only data you are authorized to access.

### Example input

```json
{
  "mode": "liveSearch",
  "seedTopics": ["控糖饮食", "糖尿病保健品", "餐后血糖"],
  "brandKeywords": ["品牌甲", "品牌乙"],
  "relatedKeywords": ["副作用", "升糖", "主食", "价格", "效果"],
  "customClusters": [
    {"name": "diet-and-staples", "keywords": ["控糖饮食", "主食", "升糖"]},
    {"name": "safety-and-evidence", "keywords": ["副作用", "临床", "证据", "安全吗"]}
  ],
  "monitorKey": "diabetes-content-cn",
  "maxPostsPerTopic": 20,
  "maxTotalPosts": 100,
  "rememberBaseline": true
}
````

### Continuous monitoring

Save a configured run as an Apify Task and add a daily or weekly Schedule. Reuse the same `monitorKey`. The first successful run creates a private aggregate baseline. Later runs compare post counts for topics, terms, and clusters against it.

Use `resetBaseline` when you intentionally change the topic set or sampling method.

### Pricing

**$4.99 per report for up to five seed topics and 100 unique posts.**

The paid event is emitted only when at least one usable post matches the seed topics. Platform usage is included in the customer price; Apify may also display its standard tiny Actor-start event.

### Limitations

- Search results are ranked samples, not the platform's complete topic universe.
- Post-count growth reflects comparable collected samples, not an official platform volume index.
- Public engagement counters change over time and can be incomplete.
- Semantic classification is deterministic and auditable; add custom clusters for specialized medical, technical, or category language.
- Opportunity scores indicate whitespace candidates, not guaranteed performance.
- Follow platform terms, privacy obligations, advertising rules, and applicable law.

# Actor input Schema

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

Try the demo, analyze uploaded current/previous notes without a Cookie, or search Xiaohongshu with your own session.

## `seedTopics` (type: `array`):

The product, need, scenario, problem, or category topics to map. Required outside demo mode.

## `brandKeywords` (type: `array`):

Optional brand and competitor terms used to calculate post and engagement penetration.

## `relatedKeywords` (type: `array`):

Optional concerns, use cases, attributes, formats, or decision terms to measure alongside discovered hashtags and semantic cues.

## `customClusters` (type: `array`):

JSON objects such as {"name":"diabetes-diet","keywords":\["控糖饮食","升糖","主食"]}.

## `uploadedNotes` (type: `array`):

For uploaded mode: current Xiaohongshu post objects. Common field names and nested note\_card shapes are normalized.

## `previousNotes` (type: `array`):

Older comparable posts for immediate growth calculations. Otherwise the last successful run with the same monitor key is used.

## `cookie` (type: `string`):

Required only for live search. Never included in logs or output.

## `monitorKey` (type: `string`):

Reuse a stable name such as diabetes-content-cn for scheduled comparisons.

## `rememberBaseline` (type: `boolean`):

Stores a compact private aggregate snapshot for the next run with the same monitor key.

## `resetBaseline` (type: `boolean`):

Start a new comparison series and save this successful run as the next baseline.

## `maxPostsPerTopic` (type: `integer`):

Maximum search results requested for each seed topic, subject to the 100-post report cap.

## `maxTotalPosts` (type: `integer`):

One $4.99 report analyzes up to 100 unique posts.

## `includeSourcePosts` (type: `boolean`):

Include the annotated posts behind every topic, trend, brand, and opportunity finding.

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

Residential proxy is recommended for live authenticated search.

## Actor input object example

```json
{
  "mode": "demo",
  "seedTopics": [],
  "brandKeywords": [],
  "relatedKeywords": [],
  "customClusters": [],
  "uploadedNotes": [],
  "previousNotes": [],
  "rememberBaseline": true,
  "resetBaseline": false,
  "maxPostsPerTopic": 20,
  "maxTotalPosts": 100,
  "includeSourcePosts": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `reports` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("scrupulous_buckler/xiaohongshu-topic-semantic-content-opportunity-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("scrupulous_buckler/xiaohongshu-topic-semantic-content-opportunity-radar").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call scrupulous_buckler/xiaohongshu-topic-semantic-content-opportunity-radar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=scrupulous_buckler/xiaohongshu-topic-semantic-content-opportunity-radar",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Xiaohongshu Topic Semantic & Content Opportunity Radar",
        "description": "Turn RedNote topic searches into related terms, semantic clusters, trend velocity, brand penetration, top and latest content, and evidence-linked content whitespace.",
        "version": "0.1",
        "x-build-id": "jHQg5tN5Y3qrt0rJg"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/scrupulous_buckler~xiaohongshu-topic-semantic-content-opportunity-radar/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-scrupulous_buckler-xiaohongshu-topic-semantic-content-opportunity-radar",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/scrupulous_buckler~xiaohongshu-topic-semantic-content-opportunity-radar/runs": {
            "post": {
                "operationId": "runs-sync-scrupulous_buckler-xiaohongshu-topic-semantic-content-opportunity-radar",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/scrupulous_buckler~xiaohongshu-topic-semantic-content-opportunity-radar/run-sync": {
            "post": {
                "operationId": "run-sync-scrupulous_buckler-xiaohongshu-topic-semantic-content-opportunity-radar",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "mode": {
                        "title": "Data source",
                        "enum": [
                            "demo",
                            "uploadedNotes",
                            "liveSearch"
                        ],
                        "type": "string",
                        "description": "Try the demo, analyze uploaded current/previous notes without a Cookie, or search Xiaohongshu with your own session.",
                        "default": "demo"
                    },
                    "seedTopics": {
                        "title": "Seed topics (maximum 5)",
                        "type": "array",
                        "description": "The product, need, scenario, problem, or category topics to map. Required outside demo mode.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "brandKeywords": {
                        "title": "Brands to measure",
                        "type": "array",
                        "description": "Optional brand and competitor terms used to calculate post and engagement penetration.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "relatedKeywords": {
                        "title": "Related terms to track",
                        "type": "array",
                        "description": "Optional concerns, use cases, attributes, formats, or decision terms to measure alongside discovered hashtags and semantic cues.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "customClusters": {
                        "title": "Optional custom semantic clusters",
                        "type": "array",
                        "description": "JSON objects such as {\"name\":\"diabetes-diet\",\"keywords\":[\"控糖饮食\",\"升糖\",\"主食\"]}.",
                        "default": []
                    },
                    "uploadedNotes": {
                        "title": "Current post sample",
                        "type": "array",
                        "description": "For uploaded mode: current Xiaohongshu post objects. Common field names and nested note_card shapes are normalized.",
                        "default": []
                    },
                    "previousNotes": {
                        "title": "Optional previous post sample",
                        "type": "array",
                        "description": "Older comparable posts for immediate growth calculations. Otherwise the last successful run with the same monitor key is used.",
                        "default": []
                    },
                    "cookie": {
                        "title": "Xiaohongshu Cookie (secret)",
                        "type": "string",
                        "description": "Required only for live search. Never included in logs or output."
                    },
                    "monitorKey": {
                        "title": "Stable monitor name",
                        "type": "string",
                        "description": "Reuse a stable name such as diabetes-content-cn for scheduled comparisons."
                    },
                    "rememberBaseline": {
                        "title": "Remember this run as the next baseline",
                        "type": "boolean",
                        "description": "Stores a compact private aggregate snapshot for the next run with the same monitor key.",
                        "default": true
                    },
                    "resetBaseline": {
                        "title": "Ignore the saved baseline this time",
                        "type": "boolean",
                        "description": "Start a new comparison series and save this successful run as the next baseline.",
                        "default": false
                    },
                    "maxPostsPerTopic": {
                        "title": "Posts per seed topic",
                        "minimum": 1,
                        "maximum": 50,
                        "type": "integer",
                        "description": "Maximum search results requested for each seed topic, subject to the 100-post report cap.",
                        "default": 20
                    },
                    "maxTotalPosts": {
                        "title": "Total posts (maximum 100)",
                        "minimum": 1,
                        "maximum": 100,
                        "type": "integer",
                        "description": "One $4.99 report analyzes up to 100 unique posts.",
                        "default": 100
                    },
                    "includeSourcePosts": {
                        "title": "Include normalized source evidence",
                        "type": "boolean",
                        "description": "Include the annotated posts behind every topic, trend, brand, and opportunity finding.",
                        "default": true
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "Residential proxy is recommended for live authenticated search.",
                        "default": {
                            "useApifyProxy": false
                        }
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```