Developer Docs

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.

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"
  }
}

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.08 Request-time analysis

Trends

/v1/china/trends

Trend momentum, related keywords, themes, and content-angle summaries for a keyword or topic, with confidence tied to the strength of the retrieved evidence.

Best for: Monitoring topic momentum

keyword platform timeframe industry region lang

$0.08 Request-time analysis

Trends (Douyin)

/v1/china/trends/douyin

Douyin-specific trend discovery with a forced Douyin retrieval lane and narrower Douyin-first query shaping.

Best for: Douyin-first topic monitoring

keyword timeframe industry region lang

$0.08 Request-time analysis

Trends (WeChat)

/v1/china/trends/wechat

WeChat-specific trend discovery with a forced WeChat retrieval lane and narrower WeChat-article query shaping.

Best for: WeChat narrative checks

keyword timeframe industry region lang

$0.08 Request-time analysis

Trends (RED)

/v1/china/trends/red

RED-specific trend discovery using the current RED-proxy evidence posture with RED-focused query shaping.

Best for: RED-proxy trend discovery

keyword timeframe industry region lang

$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 Trends

/v1/market-data/spend/trends

Country-level destination spend trend pack for downstream planning and prioritization.

Best for: Tracking market direction

country

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