Skip to content

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.

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.