Developer docs

Free JSON and CSV access to all the trade data on World Trade Flows. No auth, no rate limits beyond Vercel's defaults, and no commercial restrictions beyond the underlying CEPII BACI license (CC BY-NC-SA 4.0).

Quick start

Every dataset rendered on this site is also available as a static JSON file under /data/.... Hit any of the endpoints below directly:

# Country profile
curl https://www.worldtradeflows.com/data/yearly/2023/countries/japan.json

# Bilateral trade pair
curl https://www.worldtradeflows.com/data/yearly/2023/bilateral/japan-usa.json

# Historical series
curl https://www.worldtradeflows.com/data/historical/japan.json

# CSV download
curl 'https://www.worldtradeflows.com/api/download?type=country&slug=japan&filter=exports&format=csv'

Endpoints

/data/countries.json

Master list of every country with slug, name, ISO codes, and continent.

Example: /data/countries.json

Format: JSON object with `countries` array.

/data/yearly/2023/countries/{slug}.json

Full country profile: total exports, total imports, summary stats, top trade partners (top 20 + full list), top product categories.

Example: /data/yearly/2023/countries/japan.json

Format: JSON object with `country`, `summary`, `top_export_destinations`, `top_import_sources`, `top_export_products`, `top_import_products`, `full_exports`, `full_imports`.

/data/yearly/2023/bilateral/{country_a}-{country_b}.json

Bilateral trade pair: exports each direction, top product flows. Available for ~500 pre-built pairs.

Example: /data/yearly/2023/bilateral/japan-usa.json

Format: JSON object with `country_a`, `country_b`, `a_to_b`, `b_to_a`, `total_trade`, `balance`.

/data/yearly/2023/rankings.json

Top exporters and top importers by 2023 trade value, all 226 countries ranked.

Example: /data/yearly/2023/rankings.json

Format: JSON object with `top_exporters` and `top_importers` arrays.

/data/yearly/2023/global-totals.json

World aggregate trade values for 2023.

Example: /data/yearly/2023/global-totals.json

Format: JSON with global totals and meta.

/data/historical/{slug}.json

1995–2023 annual export/import series for that country.

Example: /data/historical/japan.json

Format: JSON with `years`, `exports`, `imports` arrays.

/data/products/{slug}.json

Aggregated trade for an HS chapter or HS6 product line: top exporting countries, top importing countries.

Example: /data/products/vehicles.json

Format: JSON with `code`, `name`, `totalExports`, `totalImports`, `exporters`, `importers`.

/data/products/_index.json

Index of all product hubs.

Example: /data/products/_index.json

Format: JSON with `products` array.

/data/bilateral-products/{slug}.json

Per-exporter map of partner -> top HS6 products. Useful when you need product detail for a specific exporter.

Example: /data/bilateral-products/japan.json

Format: JSON object keyed by partner slug.

/api/download

Server-rendered CSV/JSON download. Pass `type=country|bilateral`, `slug=...`, optional `filter=exports|imports`, `format=csv|json|xlsx`, `year=2023`.

Example: /api/download?type=country&slug=japan&filter=exports&format=csv

Format: Streaming download. CSV by default.

/sitemap.xml

Full URL inventory for crawlers.

Example: /sitemap.xml

Format: XML sitemap.

/llms.txt

Curated overview for LLM crawlers; pairs with /llms-full.txt for the deep version.

Example: /llms.txt

Format: Plain text.

Licensing & attribution

All data is derived from the CEPII BACI dataset (CC BY-NC-SA 4.0). When using data from this API in published work, attribute both:

  1. This site as the immediate source: World Trade Flows (worldtradeflows.com), accessed YYYY-MM-DD.
  2. CEPII BACI as the underlying database: Gaulier, G. and Zignago, S. (2010). BACI: International Trade Database at the Product-Level. CEPII Working Paper, N°2010-23.

For AI agents and crawlers

We publish two LLM-friendly summary files: /llms.txt (concise) and /llms-full.txt (deep reference with caveats and citation guidance). The site's sitemap contains the full URL inventory.

Caveats

  • Data is annual and not real-time. Latest year is 2023; 2024 expected in early 2026.
  • Merchandise (goods) only. Services trade is not included.
  • Values are current USD; not inflation-adjusted across years.
  • HS6 product detail; aggregations to HS2 also exposed via /product.