China Data API Docs

Free JSON and CSV endpoints for China's official government statistics. No authentication required.

Developer quick start

Fetch China GDP, trade, population, and CPI in one request.

Use the JSON endpoint for apps and charts, or append ?format=csv for spreadsheet-friendly downloads. Need official source context? Start with the NBS API guide or the GACC customs API guide.

Browse datasets NBS API guide GACC API guide
PBC money data SAFE forex data CAAM auto data MOT transport data

Base URL

https://chinadata.live/api/v2

Try it now

curl https://chinadata.live/api/v2/data/china-gdp
curl -L "https://chinadata.live/api/v2/data/china-gdp?format=csv"

Get Dataset

GET /data/:dataset_id?format=csv

Returns metadata and all data points for a specific dataset in JSON. Add ?format=csv for CSV output.

Example Request

curl https://chinadata.live/api/v2/data/china-gdp
curl -L "https://chinadata.live/api/v2/data/china-gdp?format=csv"

Example Response

{
  "success": true,
  "data": {
    "id": "china-gdp",
    "slug": "china-gdp",
    "title": "GDP (Gross Domestic Product)",
    "category": "Economy",
    "description": "China's annual GDP in current prices (100M CNY), 1960 to 2025. Source: World Bank / NBS.",
    "source": "World Bank / National Bureau of Statistics",
    "unit": "100 Million CNY",
    "frequency": "yearly",
    "tags": ["economy", "gdp", "growth"],
    "isComparison": false,
    "data": [
      { "date": "1960", "value": 1473.3 },
      { "date": "2000", "value": 101308.6 },
      { "date": "2025", "value": 1401879 }
    ]
  }
}

Python

import requests

response = requests.get('https://chinadata.live/api/v2/data/china-gdp')
dataset = response.json()['data']

print(f"Dataset: {dataset['title']}")
print(f"Unit: {dataset['unit']}")
for point in dataset['data'][-5:]:  # last 5 years
    print(f"  {point['date']}: {point['value']}")

Python + pandas

import requests
import pandas as pd

response = requests.get('https://chinadata.live/api/v2/data/china-gdp')
dataset = response.json()['data']

df = pd.DataFrame(dataset['data'])
df['date'] = pd.to_numeric(df['date'])
df['value'] = pd.to_numeric(df['value'])
df = df.set_index('date')

print(df.tail(10))
# df.plot(title=dataset['title'])

JavaScript / Node.js

const res = await fetch('https://chinadata.live/api/v2/data/china-gdp');
const { data } = await res.json();

console.log(data.title, data.unit);
data.data.slice(-5).forEach(({ date, value }) => {
  console.log(`${date}: ${value}`);
});

Trade API

Public China trade endpoints expose cleaned GACC monthly customs data for country pages, HS product previews, HS chapter/category pages, and HS-country opportunity pages. Values are numeric JSON fields; country and HS chapter endpoints use the public country-month table, while HS6/HS8 product endpoints use the curated product preview tables.

GET /trade/country/:country?breakdown=full
GET /trade/hs/:hs_code?flow=export&period=all&limit=20
GET /trade/hs/:chapter_code?breakdown=full

HS chapter/category pages use the same HS endpoint with a 2-digit chapter_code, for example 85 for electrical machinery. The site does not expose a separate /trade/category/:chapter JSON route; category slugs map to HS chapter codes before calling /trade/hs/:chapter_code.

Example Requests

curl https://chinadata.live/api/v2/trade/country/united-states
curl "https://chinadata.live/api/v2/trade/country/united-states?breakdown=full"
curl "https://chinadata.live/api/v2/trade/hs/850760?flow=export&period=all&limit=20"
curl "https://chinadata.live/api/v2/trade/hs/85?breakdown=full"

The former HS-country monthly endpoint now returns 410 hs_country_d1_endpoint_retired. It was backed by retired D1 Gold tables that are dropped after HS product serving moved to R2-only; use the static country opportunity pages or request a scoped country-month extract.

Common Response Fields

Field Meaning
coverage First period, latest period, row count, and scope for the returned public snapshot.
latest_period Latest loaded month or period represented in the response.
source / source_url Source name and source landing page or query URL where available.
retrieved_at / coverage.updated_at Nullable source retrieval or pipeline update timestamp when the public snapshot includes it; country and HS chapter responses currently return null until that timestamp is available.
qa_flags Machine-readable QA labels on a row or response, such as negative_trade_value.
suppressed_values Raw value metadata for values intentionally returned as null pending review.
known_limitations Documented limitations for public preview endpoints, row caps, or source review status.

Negative Value Suppression

Monthly import/export trade values should not be negative without an explicit source note. When a public country API snapshot sees a negative monthly value, the API returns the public value as null and keeps the raw value in QA metadata. 

{
  "year": 2026,
  "month": 1,
  "exports": 100,
  "imports": null,
  "balance": null,
  "review_status": "suppressed_negative_value",
  "raw_value": -23,
  "qa_flags": ["negative_trade_value"],
  "source_review": "pending",
  "suppressed_values": {
    "imports": {
      "review_status": "suppressed_negative_value",
      "raw_value": -23,
      "qa_flags": ["negative_trade_value"],
      "source_review": "pending",
      "action": "set_null"
    }
  }
}

Parameters and Limits

HS6/HS8 product endpoints support flow, period, and limit, and return JSON only (full CSV/Excel deliveries are scoped in custom data quotes or delivery notes). The public partner ranking limit is capped at 20 rows. Country and HS chapter endpoints support breakdown=full for compact per-month breakdown rows.

Trade Availability Schema

A dataset may be discoverable through the API before its full data file has been pre-generated. Use availability=1 to check whether an HS request is ready, available on request, requires a coverage check, or is unavailable.

GET /trade/hs/:hs_code?flow=export&period=2025&availability=1
Status Meaning
ready A file is prepared and checked. Manual delivery follows payment instructions.
available_on_request Official source coverage is likely or already visible in public preview; the full file is prepared after request.
coverage_check_required The exact HS code, period, flow, or fields have not been confirmed yet.
unavailable Usable source coverage could not be confirmed for this combination. 
{
  "success": true,
  "hs_code": "850760",
  "flow": "export",
  "period": "2025",
  "status": "available_on_request",
  "pre_generated": false,
  "source_coverage_confirmed": true,
  "payment_required": false,
  "coverage_confirmed_before_payment": true,
  "delivery_mode": "manual",
  "available_formats": ["csv", "json"],
  "request_url": "/china-trade/request/?hs=850760&flow=export&period=2025&status=available_on_request"
}

List All Datasets

GET /datasets

Returns a list of all available datasets with metadata (no data points).

Example Request

curl https://chinadata.live/api/v2/datasets

Example Response

{
  "success": true,
  "data": [
    {
      "id": "china-gdp",
      "slug": "china-gdp",
      "title": "GDP (Gross Domestic Product)",
      "category": "Economy",
      "description": "China's annual GDP in current prices (100M CNY), 1960 to 2025.",
      "unit": "100 Million CNY",
      "frequency": "yearly",
      "tags": ["economy", "gdp"]
    },
    ...
  ]
}

Python — fetch all datasets

import requests

response = requests.get('https://chinadata.live/api/v2/datasets')
datasets = response.json()['data']

print(f"Total datasets: {len(datasets)}")
for ds in datasets:
    print(f"  {ds['id']:30s} {ds['category']}")

JavaScript

const res = await fetch('https://chinadata.live/api/v2/datasets');
const { data } = await res.json();

const economy = data.filter(ds => ds.category === 'Economy');
console.log('Economy datasets:', economy.map(ds => ds.id));

Formats, Errors, and API Versioning

Response Formats

JSON is the default format for all public endpoints. CSV is supported for generic dataset endpoints with ?format=csv. HS6/HS8 product, country, and HS chapter/category endpoints currently return JSON only.

Error Codes

Status Typical Causes
400 Invalid HS code, unsupported country flow, or invalid period parameter.
404 Dataset, country, HS product, flow, or requested period is not loaded in the public snapshot.
500 Unexpected server or database error.

API Versioning

The current public API version is /api/v2. Additive fields may be added to existing responses. Breaking changes, renamed fields, or incompatible query behavior will use a new version path or be documented in delivery notes for custom feeds.

Free endpoints are intended for evaluation, research, and light usage. Higher limits, recurring feeds, delivery SLAs, file schemas, and pagination contracts are confirmed separately for paid or custom data work.

FAQ

Do I need an API key?

No. Current public endpoints require no authentication or registration. Access remains subject to the Terms of Use.

Is there a rate limit?

Yes. Anonymous access is limited to 100 requests per IP per UTC day. Check the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

What response format is used?

All endpoints return JSON. Dates are strings (e.g. "2023"), values are numbers.

Can I download raw CSV data?

Yes — visit any dataset page and click the download button, or call the dataset endpoint with ?format=csv, for example https://chinadata.live/api/v2/data/china-gdp?format=csv.

Ready to Start?

No sign-up or API key for current public endpoints. Fair-use limits and terms apply.

Browse Datasets More Examples

API use is governed by the Terms of Use. Source and redistribution rules are in Data Use & Licensing.

Need higher limits or custom data?

Commercial API access, bulk exports, custom datasets, and dedicated support available.

Contact Us →
💬 Need custom data?