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 the official raw NBS endpoint details? See the data.stats.gov.cn API guide.

Browse datasets NBS API guide

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&format=csv
GET /trade/hs/:chapter_code?breakdown=full
GET /trade/hs/:hs_code/country/:country?period=all

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 -L "https://chinadata.live/api/v2/trade/hs/850760?flow=export&period=all&format=csv"
curl "https://chinadata.live/api/v2/trade/hs/85?breakdown=full"
curl "https://chinadata.live/api/v2/trade/hs/850760/country/united-states?period=all"

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, limit, and format=csv. The public partner ranking limit is capped at 20 rows. Country and HS chapter endpoints support breakdown=full for compact per-month breakdown rows. Large recurring feeds, pagination contracts, and full CSV/Excel deliveries are scoped in custom data quotes or delivery notes.

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 and HS6/HS8 product preview endpoints with ?format=csv. 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 may use a configurable daily limit, currently defaulting to 100 requests where enforcement is enabled. 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?