# 📺 Bilibili Trends Watch — Trending & Ranking Deltas (`nexgenwatch/bilibili-trends-watch`) Actor

Bilibili public trending/popular/ranking watch — new and changed entries with deltas; original Chinese retained alongside translation.

- **URL**: https://apify.com/nexgenwatch/bilibili-trends-watch.md
- **Developed by:** [NexGen Watch](https://apify.com/nexgenwatch) (community)
- **Categories:** Business, Social media
- **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.10 / 1,000 trend deltas

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
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

## Bilibili Public Trends Delta Watch

Watch public Bilibili Popular, rankings, and selected searches for confirmed entry, exit, rank, and engagement changes.

### 1. What it does

The actor records logged-out Bilibili public trend surfaces, establishes a zero-alert first-run baseline, and emits only qualified changes afterward. It is built for media monitoring, market research, agencies, and APAC brand teams needing record-backed recurring collection rather than dashboard screenshots. Snapshot mode returns current records; watch mode seeds a private baseline and returns confirmed later deltas. Receipts separate complete, empty, partial, and blocked checks.

Original Chinese-script titles are always retained (`title_original`). A `title_translated` field carries a published translation only and is `null` otherwise — the actor never machine-translates silently.

### 2. Input

`surfaces` (popular, ranking, search), `keywords` (required for search), `rankingCategories`, `watchMode`, `baselineId`, `pageCount`, `topN`, `rankChangeThreshold`, `metricChangePercent`, `exitConfirmations`, `includeDescriptions`, `maxItems`, `maxRequests`. No arbitrary URLs are accepted; keywords and ranking categories are validated against §1 bounds.

Example input:

```json
{"surfaces":["popular","search"],"keywords":["人工智能","新能源汽车"],"watchMode":true,"pageCount":2,"topN":100,"rankChangeThreshold":5,"metricChangePercent":20,"exitConfirmations":2,"includeDescriptions":false,"maxItems":500,"maxRequests":50}
```

### 3. Output

Three record types: `trend_record` (normalized ranked video with bilingual titles, metrics, and `content_hash`), `trend_delta` (entered / rank\_changed / engagement\_changed / exited / reentered with `rank_change`, `metric_changes`, `changed_fields`), and `source_receipt` (per surface/query terminal: NORMAL / GENUINE\_EMPTY / PARTIAL / BLOCKED). Every item carries `record_type`, `schema_version`, `run_id`, exact `source_url`, and `observed_at`.

### 4. Pricing

Pay-per-event: actor start, trend record, trend delta, and watch source check. Amounts are configured at publish. `source_receipt` items are always returned and never billed.

### 5. Watch mode

Named key-value store `bilibili-trends-v1-{baselineId}` holds the baseline. The first complete run seeds and emits zero deltas. Later scheduled runs emit at most one confirmed delta per video, combining rank and engagement changes. A video is exited only after it is absent from the complete topN for `exitConfirmations` consecutive eligible runs; partial or blocked surfaces never increment absence. Same video = exact composite key `surface|normalized-query-or-category|bvid`.

### 6. API, CLI, and MCP

Runs on the Apify platform via API, CLI, schedules, and MCP like any Actor. Watch state persists in the named key-value store; each run is independent and stateless over that store.

### 7. Use with

China media teams monitoring high-heat videos; agencies watching category movement; brands tracking public topic/search visibility; researchers building time-stamped chart histories.

### 8. Honest limits

Bilibili's web data endpoints are undocumented and volatile; search results may vary; no historical backfill, comments, account-only data, login, CAPTCHA solving, or risk-control bypass. `exited` means absent from the configured complete topN, not deleted from Bilibili. The actor stops loudly (BLOCKED) when anonymous public access or the required shape cannot be proved.

### 9. Compliance

Public logged-out GET only; no accounts, cookies, QR login, copied signatures, CAPTCHA solving, or proxy evasion. Comply on objection. Buyers are responsible for lawful use and source terms.

### Pricing

| Event | FREE | BRONZE | SILVER | GOLD+ |
|---|---|---|---|---|
| Actor start (`actor-start`) | $0.02 | $0.02 | $0.02 | $0.02 |
| Trend record (`trend-record`) | $0.02 | $0.018 | $0.016 | $0.0134 |
| Trend delta (`trend-delta`) | $0.03 | $0.027 | $0.024 | $0.0201 |
| Source check (`source-check`) | $0.10 | $0.09 | $0.08 | $0.067 |

Prices are the filed pay-per-event amounts per plan tier (PLATINUM/DIAMOND match GOLD). Blocked and refused runs do not intentionally charge value events.

# Actor input Schema

## `surfaces` (type: `array`):

Public logged-out Bilibili surfaces to watch: popular, ranking, and/or search. 1-3 unique.

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

Required when 'search' is selected. 1-20 keywords, each 1-40 Unicode characters, no URL syntax.

## `rankingCategories` (type: `array`):

Bilibili ranking rid values from the build-time allowlist; 0 means all. Used only for the 'ranking' surface.

## `watchMode` (type: `boolean`):

Seed a private baseline and emit only confirmed later deltas (entered/rank\_changed/engagement\_changed/exited/reentered). First complete run emits zero deltas. False emits current snapshot rows.

## `baselineId` (type: `string`):

Named watch baseline (^\[A-Za-z0-9\_-]{3,64}$). Changing page depth, topN, or inputs derives a new baseline.

## `pageCount` (type: `integer`):

Pages to read for popular/search (subject to the source cap).

## `topN` (type: `integer`):

Tracked rank depth per surface/query.

## `rankChangeThreshold` (type: `integer`):

Minimum absolute rank movement (positions) to emit a rank\_changed delta. Entry/exit unaffected.

## `metricChangePercent` (type: `integer`):

Minimum percent change in a metric (denominator > 0) to emit an engagement\_changed delta.

## `exitConfirmations` (type: `integer`):

Consecutive complete observations a video must be absent from the complete topN before it is confirmed exited.

## `includeDescriptions` (type: `boolean`):

Include the public list/detail summary (<= 10 KiB). No extra request by default.

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

Maximum value rows to emit this run (receipts excluded).

## `maxRequests` (type: `integer`):

Hard logical-request budget for the run.

## Actor input object example

```json
{
  "surfaces": [
    "popular"
  ],
  "keywords": [],
  "rankingCategories": [
    0
  ],
  "watchMode": true,
  "pageCount": 2,
  "topN": 100,
  "rankChangeThreshold": 5,
  "metricChangePercent": 20,
  "exitConfirmations": 2,
  "includeDescriptions": false,
  "maxItems": 1000,
  "maxRequests": 50
}
```

# 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("nexgenwatch/bilibili-trends-watch").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("nexgenwatch/bilibili-trends-watch").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 nexgenwatch/bilibili-trends-watch --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=nexgenwatch/bilibili-trends-watch",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/OfuwdwElzQt3NqVfh/builds/riXfhpWapUp03pSyK/openapi.json