Skip to content

Documentation

Build with China Marketing AI

Start with one integration path, then move into API routes, agent workflows, or MCP setup as your implementation needs deeper detail.

x402 paid requests Decision-ready envelopes Agent-ready capability wrappers Remote MCP endpoint
Start with the API quickstart Explore agent docs Open MCP quickstart

Choose your documentation path

One hub, three implementation depths

API / Developers

Make paid x402 requests, inspect response contracts, handle errors, and work with route-level China intelligence primitives.

Best for: Direct API calls, schema-level detail, pricing, examples, request handling, and response handling.

Start API quickstart

Agents

Use capability wrappers for brand visibility, destination demand, creator shortlisting, and other decision-ready China market tasks.

Best for: Agent workflows, orchestration layers, scheduled monitoring, and budget-aware execution.

Open agent docs

MCP

Connect compatible clients to the China Marketing AI remote MCP server and call flagship intelligence tools through a standard tool interface.

Best for: MCP clients, agent connectors, remote server setup, tool calls, and response parsing.

Open MCP quickstart

First tasks

Start with the job you need to complete

Make one paid API request Use x402 payment proof and inspect the standard response envelope. Build an agent workflow Map a task to a capability wrapper and return a decision-ready output. Connect through MCP Use the remote MCP endpoint and call a flagship wrapper from a compatible client. Handle errors and debugging Use stable error codes and meta.request_id as the support and debugging anchor. Understand response design Work with data, meta, pricing, confidence, evidence posture, and source summaries.

Flagship capability paths

Most integrations start with one high-value task before dropping into deeper route detail

Brand Visibility

Diagnose where a brand is visible, weak, or missing across China-facing discovery surfaces.

Agent framing Route detail

Destination Demand

Read outbound China demand direction using movement, spend, and destination signal context.

Agent framing Route detail

KOL Shortlist

Generate a creator shortlist with rationale, risk flags, fit signals, and recommended next steps.

Agent framing Route detail

Core implementation standards

Keep payment, response, evidence, and cost behavior explicit

Payment

Current paid routes use x402 payment proof. No API key is required unless a future route explicitly states otherwise.

Response envelope

Successful responses expose structured data, request metadata, and pricing context.

Errors

Errors preserve a stable code, readable message, and request identifier for debugging.

Evidence posture

Platform parameters guide retrieval, but response contracts should disclose confidence and evidence posture where relevant.

Cost visibility

Agent and API workflows should preserve per-request cost context so automation layers can reason about budget.

API quickstart and route reference

Start with one paid request, one unpaid retry path, and one standard envelope

Use x402 payment proof in the request header, expect structured JSON on success, and treat `meta.request_id` as the debugging anchor when a request fails.

Agent workflows

Looking to build agent workflows?

Start with the capability layer to map tasks such as visibility snapshots, creator scouting, and travel movement to the right primitives.

Explore agent capabilities

No API key required. Core API access is payment-gated via x402. No API key is required unless a future route explicitly states otherwise.

Execution time

Dataset-backed routes usually return quickly. Live provider-backed routes can take roughly 30 to 45 seconds, so buyers should keep the connection open and use the returned artifact path instead of retrying payment.

Minimal Paid Request

bash

curl "https://api.chinamarketing.ai/v1/china/trends?keyword=outbound%20travel&platform=red&timeframe=30d" \
  -H "x402-payment: <payment_proof>"

Successful Response

json

{
  "success": true,
  "data": {
    "keyword": "outbound travel",
    "platform": "red",
    "summary": {
      "momentum": "rising",
      "confidence": 0.74,
      "themes": ["visa-free travel", "short-haul luxury", "Japan itineraries"]
    }
  },
  "meta": {
    "request_id": "req_demo",
    "generated_at": "2026-04-10T12:00:00Z",
    "pipeline_version": "v1"
  },
  "pricing": {
    "amount_usd": "0.08",
    "payment_status": "paid"
  }
}

Errors

  • 402 payment_required
  • Stable error shape
  • Use meta.request_id for debugging

Response contract

Successful responses include `data`, `meta`, and `pricing`. Errors include a stable `error.code`, a readable `message`, and the same `meta.request_id` anchor for support and log correlation.

Weekly signals contract

Signal endpoints expose published weekly snapshots across creators, topics, brands, and categories. Rankings use `category` plus a route-specific `rank_type`, while snapshots add freshness metadata.

Evidence posture

Platform parameters steer retrieval toward the best available lane, but not every China platform is equally indexable. RED requests currently behave as RED-proxy reads unless stronger native evidence is available.

Payment Required

json

{
  "success": false,
  "error": {
    "code": "payment_required",
    "message": "Payment is required before this resource can be accessed."
  },
  "meta": {
    "request_id": "req_demo"
  }
}

Capability wrappers

Use the agent-first wrapper routes when you want one decision-ready contract per task

These additive routes keep the raw endpoint families intact while packaging the most common agent jobs into one paid call with cost, recommendation, confidence, source summary, and optional session continuity.

$0.63 orchestrated

Brand Visibility Snapshot

/v1/visibility/snapshot

Generate a China brand visibility snapshot with summary assessment, scored strengths and gaps, and priority actions.

Required inputs: brand_name

Output contract: summary, score, strengths, gaps, priority_actions, sources

Typical wait: about 45s. Live provider-backed visibility runs can take up to 45 seconds. Keep the request open while the system gathers trend, sentiment, and optional weekly snapshot context.

Underlying routes: /v1/china/trends, /v1/china/sentiment, /v1/signals/brands/:brand_slug/snapshot

$0.20 orchestrated

Destination Demand Snapshot

/v1/destination-demand/snapshot

Generate a China outbound destination demand snapshot with demand direction, notable signals, risk framing, and priority actions.

Required inputs: destination

Output contract: summary, demand_direction, notable_signals, opportunity_areas, risks, priority_actions

Typical wait: about 15s. Destination demand usually returns quickly. Spend context is included when the destination can be mapped cleanly to a supported market.

Underlying routes: /v1/market-data/flights/summary, /v1/market-data/spend/trends

$0.45 direct

KOL Shortlist

/v1/kol/shortlist

Generate a decision-ready China KOL shortlist with creator candidates, selection rationale, risk flags, and next steps.

Required inputs: brand_name, category

Output contract: summary, creators, selection_rationale, risks, next_steps

Typical wait: about 35s. Shortlist generation can take up to 35 seconds when provider-backed discovery is required. Keep the request open rather than retrying.

Underlying routes: /v1/china/kols

China intelligence

Trend, sentiment, and KOL routes for programmatic checks across China platform topics and narratives.

Starting from $0.08. Use the anchors below for direct links to individual routes.

Example: trends request · Request

bash

curl "https://api.chinamarketing.ai/v1/china/trends?keyword=outbound%20travel&platform=red&timeframe=30d" \
  -H "x402-payment: <payment_proof>"

Example: trends request · Response

json

{
  "success": true,
  "data": {
    "keyword": "outbound travel",
    "platform": "red",
    "summary": {
      "momentum": "rising",
      "confidence": 0.74,
      "themes": ["visa-free travel", "short-haul luxury", "Japan itineraries"]
    },
    "evidence_mode": "proxy"
  },
  "meta": {
    "request_id": "req_demo",
    "generated_at": "2026-04-10T12:00:00Z",
    "pipeline_version": "v1"
  },
  "pricing": {
    "amount_usd": "0.08",
    "payment_status": "paid"
  }
}
$0.15 Request-time analysis

Sentiment

/v1/china/sentiment

Localized narrative and sentiment framing for brands, destinations, products, and topics.

Best for: Narrative framing

entity platform timeframe industry lang
$0.45 Request-time analysis

KOLs

/v1/china/kols

Focused KOL and KOC shortlists with fit scoring, engagement-quality estimates, and recommendation summaries.

Best for: Shortlist generation

category platform city tier budget_band industry

Weekly signal snapshots

Published weekly rankings and snapshots for creator, topic, brand, and category visibility monitoring.

Starting from $0.18. Use the anchors below for direct links to individual routes.

Example: brand snapshot request · Request

bash

curl "https://api.chinamarketing.ai/v1/signals/brands/lululemon/snapshot?category=athleisure&week_start=2026-03-30" \
  -H "x402-payment: <payment_proof>"

Example: brand snapshot request · Response

json

{
  "success": true,
  "data": {
    "brand_name": "lululemon",
    "brand_slug": "lululemon",
    "category": "athleisure",
    "visibility_score": 68,
    "rank_positions": {
      "brand_visibility": 3,
      "brand_seeding": 5
    },
    "summary": "lululemon holds visible weekly momentum across athleisure ranking signals.",
    "snapshot_week": "2026-03-30 to 2026-04-05",
    "week_start": "2026-03-30",
    "week_end": "2026-04-05",
    "freshness": "weekly_manual"
  },
  "meta": {
    "request_id": "req_demo",
    "generated_at": "2026-04-10T08:28:31Z",
    "pipeline_version": "v1"
  },
  "pricing": {
    "amount_usd": "0.40",
    "payment_status": "paid"
  }
}
$0.18 Weekly snapshots

Creator Rankings

/v1/signals/creators/rankings

Weekly creator rankings for a supported category and rank type, suitable for monitoring breakout presence and creator momentum.

Best for: Monitoring creator momentum

category rank_type week_start week_end limit
$0.18 Weekly snapshots

Topic Rankings

/v1/signals/topics/rankings

Weekly topic rankings for a supported category and topic rank type, returning a structured snapshot of emerging or high-volume themes.

Best for: Tracking theme visibility

category rank_type week_start week_end limit
$0.22 Weekly snapshots

Brand Rankings

/v1/signals/brands/rankings

Weekly brand rankings for a supported category and brand rank type, deduped to one brand-level row per response item.

Best for: Competitive visibility checks

category rank_type week_start week_end limit
$0.40 Weekly snapshots

Brand Snapshot

/v1/signals/brands/:brand_slug/snapshot

Derived weekly brand snapshot for a category, including visibility scoring, contributing rank positions, and freshness metadata.

Best for: Weekly competitive checks

category week_start week_end

Example path: /v1/signals/brands/lululemon/snapshot?category=athleisure

$0.40 Weekly snapshots

Category Snapshot

/v1/signals/categories/:category_slug/snapshot

Weekly category overview that blends top creators, topics, and brands for the latest or requested published release.

Best for: Category-level weekly overviews

week_start week_end

Example path: /v1/signals/categories/beauty/snapshot?week_start=2026-03-30

Destination spend data

Country-level market sizing, trend, and time-series endpoints grounded in destination spend source periods.

Starting from $0.03. Use the anchors below for direct links to individual routes.

Example: spend summary request · Request

bash

curl "https://api.chinamarketing.ai/v1/market-data/spend/summary?country=Japan&month=2026-02" \
  -H "x402-payment: <payment_proof>"

Example: spend summary request · Response

json

{
  "success": true,
  "data": {
    "country": "Japan",
    "source_month": "2026-02",
    "summary": {
      "total_cards": 18422,
      "estimated_average_luxury_spend_cny": 6421.5,
      "estimated_average_accommodation_spend_cny": 3180.2
    }
  },
  "meta": {
    "request_id": "req_demo",
    "generated_at": "2026-04-10T12:00:00Z",
    "pipeline_version": "v1"
  },
  "pricing": {
    "amount_usd": "0.10",
    "payment_status": "paid"
  }
}
$0.03 Month-based source periods

Spend Months

/v1/market-data/spend/months

List the available source months for the destination spend dataset.

Best for: Dataset freshness checks

No query params
$0.03 Month-based source periods

Spend Countries

/v1/market-data/spend/countries

List supported countries in the spend dataset, optionally scoped to a specific month.

Best for: Country availability checks

month
$0.10 Month-based source periods

Spend Summary

/v1/market-data/spend/summary

Latest or month-specific destination spend summary for a country, including key metrics, breakdown highlights, and data-quality context.

Best for: Country-level market sizing

country month
$0.10 Month-based source periods

Spend Series

/v1/market-data/spend/series

Time series for a supported destination spend metric such as total cards or selected average spend measures.

Best for: Time-series modeling

country metric

Flight-arrivals data

Destination-level route, ranking, growth, and aggregate views for arrival planning and destination prioritization.

Starting from $0.03. Use the anchors below for direct links to individual routes.

Example: flight aggregate request · Request

bash

curl "https://api.chinamarketing.ai/v1/market-data/flights/aggregate?destinations=Tokyo,Osaka&label=Japan%20Core" \
  -H "x402-payment: <payment_proof>"

Example: flight aggregate request · Response

json

{
  "success": true,
  "data": {
    "label": "Japan Core",
    "destinations": ["Tokyo", "Osaka"],
    "summary": {
      "estimated_passengers": 286400,
      "top_origin_city": "Shanghai",
      "growth_direction": "up"
    }
  },
  "meta": {
    "request_id": "req_demo",
    "generated_at": "2026-04-10T12:00:00Z",
    "pipeline_version": "v1"
  },
  "pricing": {
    "amount_usd": "0.16",
    "payment_status": "paid"
  }
}
$0.03 Month-based source periods

Flight Months

/v1/market-data/flights/months

List the available source months for the flight-arrivals dataset.

Best for: Dataset freshness checks

No query params
$0.10 Month-based source periods

Flight Summary

/v1/market-data/flights/summary

Latest or month-specific destination flight summary with route, seat, passenger, and concentration metrics.

Best for: Destination prioritization

destination month
$0.10 Month-based source periods

Flight Trend

/v1/market-data/flights/trend

Monthly scheduled-flight trend series for a destination.

Best for: Capacity trend tracking

destination limit
$0.10 Month-based source periods

Top Routes

/v1/market-data/flights/top-routes

Top departure cities feeding a destination in a given month.

Best for: Route mix analysis

destination month limit
$0.10 Month-based source periods

Flight Ranking

/v1/market-data/flights/ranking

Destination ranking by estimated passengers for a given or latest month.

Best for: Destination prioritization

month
$0.10 Month-based source periods

Flight Growth

/v1/market-data/flights/growth

Fastest-growing destinations by month-over-month passenger trend.

Best for: Growth scouting

month
$0.16 Month-based source periods

Flight Aggregate

/v1/market-data/flights/aggregate

Aggregate multiple destinations into one destination-cluster summary for route planning or market grouping.

Best for: Cluster planning

destinations label

Platform evidence posture

RED / Xiaohongshu

Treat current `platform=red` responses as RED-proxy evidence. The endpoint may cite open-web analysis, reports, or platform-adjacent coverage when direct RED-native indexing is not reliable enough.

WeChat

WeChat requests are routed toward Tencent-first discovery, then fall back to broader web evidence when needed.

Douyin

Douyin requests are routed toward Ark-first discovery, then broadened only if the evidence set remains too thin.