# TradeWeave — Global Trade Analytics Platform (Full Documentation)

> The most comprehensive free international trade analytics platform. Explore exports, imports, and bilateral trade data for 238 countries and 6,800+ HS6 products (1995-2024).
> For the summary version, see https://tradeweave.org/llms.txt

TradeWeave (tradeweave.org) is a free, open-access global trade analytics platform — a comprehensive alternative to the Observatory of Economic Complexity (OEC). It covers 238 countries, 6,800+ HS6 products, 30 years of BACI bilateral trade data, economic complexity rankings (ECI/PCI), tariff simulation, trade cost analysis, gravity modeling, and trade forecasting. All data is free to access with no paywall.

## Why TradeWeave over OEC?

- Completely free — no subscription required for any feature
- 49 analytics pages vs OEC's limited free tier
- Tariff impact simulator with real trade elasticities
- Gravity model estimation tool
- Supply chain risk analysis
- Bilateral trade cost analysis (ESCAP-World Bank)
- FRED/BLS freight and commodity price benchmarks
- FAO agricultural trade and food security analytics
- Historical trade data spanning 200+ years (1800-present)
- 127 REST API endpoints for programmatic data access

## Core Data

- BACI/CEPII bilateral trade data: 238 countries, 6,800+ HS6 products, 1995-2024
- Historical trade data spanning 200+ years
- World Bank Development Indicators (WDI) for macroeconomic context
- ESCAP-World Bank bilateral trade costs (1995-2018)
- WITS/TRAINS MFN and preferential tariff rates (36M+ tariff lines)
- FRED and BLS freight, price, and exchange rate indices
- FAO agricultural trade and food security data

## Analytics Pages

- [Country Exporter Profile](https://tradeweave.org/exporter): Export composition, RCA, diversification, growth for any country
- [Country Importer Profile](https://tradeweave.org/importer): Import dependency, sources, and concentration analysis
- [Bilateral Trade](https://tradeweave.org/bilateral): Bilateral trade flows, Grubel-Lloyd index, product overlap
- [Country Comparison](https://tradeweave.org/compare): Side-by-side comparison of trade profiles across countries
- [Trade Flow Map](https://tradeweave.org/flows): Interactive 3D globe and Sankey diagrams of global trade flows
- [Geographic Trade](https://tradeweave.org/geography): Choropleth maps of trade patterns by country and product
- [Rankings](https://tradeweave.org/rankings): Country rankings by trade volume, growth, and complexity
- [ECI Rankings](https://tradeweave.org/rankings/eci): Economic Complexity Index rankings and trends
- [PCI Rankings](https://tradeweave.org/rankings/pci): Product Complexity Index rankings
- [Product Space](https://tradeweave.org/product-space): Network visualization of product relatedness
- [Product Explorer](https://tradeweave.org/products): Browse and analyze 6,800+ trade products
- [Global Trends](https://tradeweave.org/global-trends): World trade growth, composition, and structural shifts
- [Tariff Simulator](https://tradeweave.org/tariff-simulator): Simulate tariff impacts using import demand elasticities
- [Trade Costs](https://tradeweave.org/trade-costs): Logistics performance, bilateral trade costs, and freight benchmarks
- [Gravity Model](https://tradeweave.org/gravity): Gravity model of trade with distance, GDP, and border effects
- [Demand Analysis](https://tradeweave.org/demand): Import demand elasticity estimates by product
- [Trade Forecasts](https://tradeweave.org/forecast): Ensemble trade forecasting with Holt's linear trend, regression, and moving average models
- [Macro Dashboard](https://tradeweave.org/macro): Macroeconomic context (GDP, inflation, exchange rates)
- [Balance of Payments](https://tradeweave.org/bop): Current account, capital flows, and external balances
- [WDI Explorer](https://tradeweave.org/wdi): World Development Indicators browser
- [Unit Values](https://tradeweave.org/unit-values): Export unit values and quality signals by product
- [Quality Upgrading](https://tradeweave.org/quality-upgrading): Product quality ladder analysis
- [Historical Trade](https://tradeweave.org/historical): Long-run trade trends (1800-present)
- [Competition Analysis](https://tradeweave.org/competition): Export competition and market overlap between countries
- [Supply Chain Risk](https://tradeweave.org/supply-chain-risk): Concentration risk and sourcing vulnerability
- [Structural Change](https://tradeweave.org/structural-change): Sectoral transformation in trade composition
- [Trade Network](https://tradeweave.org/trade-network): Network centrality and community detection in global trade
- [Trade Diagnostic](https://tradeweave.org/diagnostic): Comprehensive trade health diagnostic by country
- [Exporter Insights](https://tradeweave.org/insights): Product-level trade story — market position, barriers, competition, trends for any exporter+product pair
- [Commodity Prices](https://tradeweave.org/commodities/prices): Global commodity price tracking
- [Agricultural Trade](https://tradeweave.org/commodities/agri-trade): Agricultural trade flows and patterns
- [Food Security](https://tradeweave.org/commodities/food-security): Food import dependency and vulnerability
- [Value Chains](https://tradeweave.org/commodities/value-chains): Commodity value chain mapping
- [Intelligence Reports](https://tradeweave.org/intelligence): AI-generated trade intelligence briefings
- [Methodology](https://tradeweave.org/methodology): Data sources, methodology, and technical documentation
- [About](https://tradeweave.org/about): About TradeWeave and its mission

---

## API Endpoints

All GET endpoints return JSON. Values in "thousands of USD" (multiply by 1000 for real USD). ISO3 country codes are case-insensitive. Most endpoints accept a ?year= parameter (default 2024). Responses are cached (Cache-Control: public, max-age=3600, s-maxage=86400).

### Search

- GET /api/search?q={query} — Search countries and products by name or code. Returns mixed array of country and product results (up to 10 each).

### Country Data

- GET /api/countries — List all 238 countries with code, name, iso2, iso3.
- GET /api/countries/{iso3}?year=2024 — Country trade summary: exports, imports, trade balance, export/import rank, ECI, ECI rank, HHI, num_products, export/import growth, EODB score, NTM summary.
- GET /api/countries/{iso3}/timeseries — 30-year timeseries of total_exports, total_imports, trade_balance by year.
- GET /api/countries/{iso3}/partners?year=2024&flow=export&limit=20 — Top trading partners. flow=export|import. Returns partner name, iso3, and trade value.
- GET /api/countries/{iso3}/trade?year=2024&flow=export — Treemap hierarchy of trade by HS section > chapter > product (HS6). Returns nested children with values.
- GET /api/countries/{iso3}/trade-composition?flow=export&topN=10 — Stacked area timeseries of trade by HS section over all years. Returns data array with year + section values, keys, and color map.
- GET /api/countries/{iso3}/diversification-timeline — HHI, num_products, num_partners, Gini coefficient, and top_product_share over all years. Includes diversification trend interpretation.
- GET /api/countries/{iso3}/factor-intensity?year=2024 — Export technology classification (Primary, Resource-Based, Low-Tech, Medium-Tech, High-Tech) with breakdown shares, tech_intensity_index, and timeline over all years.
- GET /api/countries/{iso3}/market-concentration?year=2024 — Geographic export concentration: HHI of destinations, Gini, top-1/5/10 concentration ratios, top 15 partners with shares, and HHI timeline.
- GET /api/countries/{iso3}/market-power?year=2022 — Products where this country is the dominant global supplier. Returns dominant_count, monopoly_count, top 20 dominant products, and dependent countries.
- GET /api/countries/{iso3}/rca-dynamics?year=2024&window=5 — Rising and declining comparative advantages over a window. Returns top 15 rising stars and top 15 declining industries with RCA change.
- GET /api/countries/{iso3}/rca-transition?year=2024&window=5 — RCA transition matrix (Classic/Emerging/Disappearing quadrants). Shows products gaining or losing RCA>1 status over the window period.
- GET /api/countries/{iso3}/vulnerabilities?year=2022 — Supply chain vulnerability analysis using geodep data. Returns critical product count, sector breakdown, top 20 critical products, and top suppliers.
- GET /api/countries/{iso3}/products/{hs6}?year=2024 — Deep dive for a specific country+product pair. Returns timeseries, RCA, PCI, market share, export rank, top exporters, top importers, import dependency (geodep), tariff data (MFN + preferential), trade elasticity, unit values, NTM measures, and EODB trading-across-borders scores.

### Product Data

- GET /api/products?level=6 — List all products at a given HS digit level (default 6). Returns code, name, chapter, section.
- GET /api/products/{hs}/exporters?year=2024&limit=20 — Top exporting countries for a product by export value.
- GET /api/products/{hs}/importers?year=2024&limit=20 — Top importing countries for a product by import value.
- GET /api/products/{hs}/timeseries — Global trade timeseries for a product: total exports, imports, trade, and quantity by year.
- GET /api/products/{hs}/market-shares — Market share dynamics: stacked area data showing how top 8 exporters' shares shifted over all years.
- GET /api/products/{hs}/pci-trend — Product Complexity Index trend over time with PCI rank and total trade volume.
- GET /api/products/{hs}/rca-countries?year=2024&limit=30 — Countries with RCA >= 1 in this product, sorted by RCA. Includes export value, ECI, and ECI rank.
- GET /api/products/{hs}/elasticity — Import demand elasticity (sigma) for an HS6 product. Includes interpretation (inelastic/elastic/highly elastic).

### Bilateral Trade

- GET /api/bilateral/{exporter_iso3}/{importer_iso3}/timeseries — Bilateral trade timeseries between two countries (both directions). Returns forward, reverse, and balance by year.

### Country Comparison

- GET /api/compare?countries=USA,CHN,DEU&year=2024 — Compare up to 6 countries. Returns trade profiles, timeseries, and Finger-Kreinin Export Similarity Index matrix.

### Rankings

- GET /api/rankings?year=2024&sort=exports&limit=50 — Country rankings sortable by: exports, imports, balance, export_rank, import_rank, hhi, hhi_desc. Returns trade totals, growth, HHI.
- GET /api/rankings/eci?year=2024 — Economic Complexity Index rankings for all countries.
- GET /api/rankings/pci?year=2024&limit=20&min_trade=10000000 — Product Complexity Index rankings. min_trade filters noise from low-volume products.
- GET /api/rankings/volume?year=2024&sort=volume&limit=30 — Trade volume/unit value rankings. sort=volume|value|unit_price|unit_price_asc.

### Product Space

- GET /api/product-space?country={iso3}&year=2024&minProximity=0.55 — Product space network: nodes (products with RCA, export value, section) and links (proximity edges). Used for network visualization.
- GET /api/product-space/summary?country={iso3}&year=2024 — Product space summary statistics for a country.

### Global Trends

- GET /api/global-trends/volume — Global trade volume timeseries (all years).
- GET /api/global-trends/stages — Global trade by production stage (primary, semi-finished, finished) over time.
- GET /api/global-trends/gvc-index — Global Value Chain fragmentation index: parts & components share of total trade.
- GET /api/global-trends/country?country={iso3}&year=2024 — Country-level trade by production stage for a given year.

### Historical Trade

- GET /api/historical/global — Global trade timeseries spanning 200+ years (1800-present).
- GET /api/historical/pair?o={iso3}&d={iso3} — Historical bilateral trade between two countries.
- GET /api/historical/powers?year=1913&limit=10 — Top trading powers in a historical year.

### Tariffs & Trade Policy

- GET /api/tariffs/{hs4} — Tariff elasticity data for an HS4 code: epsilon (import demand elasticity), zero/positive flags.
- GET /api/tariffs/{hs4}/rates?year=2024 — MFN tariff rates by reporter country for an HS4 product. Returns avg, min, max, number of HS6 lines, free vs dutiable counts.
- GET /api/tariffs/{hs4}/pref-rates?reporter={iso3} — Preferential tariff rates by partner for an HS4 product applied by a reporting country.

### Trade Costs

- GET /api/trade-costs/{iso3}?year=2018&sector=manufacturing — ESCAP-World Bank bilateral trade costs for a country. Returns trade cost % by partner, timeseries, and sector breakdown.
- GET /api/trade-costs/rankings?year=2018&sector=manufacturing&limit=50 — Trade cost rankings across countries.
- GET /api/trade-costs/compare?countries=USA,CHN,DEU&sector=manufacturing — Compare trade costs across multiple countries.
- GET /api/trade-costs/bilateral/{iso3}?sector=manufacturing — Bilateral trade cost timeseries for a country.
- GET /api/trade-costs/fred — List available FRED economic series (freight rates, exchange rates, price indices).
- GET /api/trade-costs/fred/{series_id} — FRED timeseries data for a specific series.
- GET /api/trade-costs/bls — List available BLS trade-related series.
- GET /api/trade-costs/bls/{series_id} — BLS timeseries data for a specific series.

### Gravity Model

- GET /api/gravity/pair?o={iso3}&d={iso3}&year=2020 — Gravity model bilateral data: distance, GDP, contiguity, common language, colonial ties, actual trade, and gravity residual.
- GET /api/gravity/potential?iso3={iso3}&year=2020&limit=20 — Gravity model trade potential: partners where actual trade is below gravity-predicted levels (undertrade opportunities).

### Demand Analysis

- GET /api/demand/products?limit=50&offset=0&search={query} — Browse products with import demand elasticity estimates. Paginated.
- GET /api/demand/{hs4} — Detailed demand analysis for an HS4 product: elasticity, budget shares by country, expenditure estimates.

### Macroeconomic Data

- GET /api/macro/{iso3} — GDP, GDP per capita, population, inflation, exchange rate timeseries for a country.
- GET /api/macro/compare?countries=USA,CHN,DEU — Compare macroeconomic indicators across multiple countries.
- GET /api/macro/openness?year=2023&limit=50 — Trade openness rankings: (exports+imports)/GDP ratio by country.

### Balance of Payments

- GET /api/bop/{iso3}?year=2023 — Balance of payments flows (current account, goods, services, income, transfers) for a country and year.
- GET /api/bop/{iso3}/indicators — All BOP indicator values across all years for a country.
- GET /api/bop/{iso3}/timeseries?items=100,110,120&flow=B — BOP component timeseries. items= comma-separated BOP item codes, flow=B (balance), C (credit), D (debit).

### World Development Indicators

- GET /api/wdi?countries=USA,CHN&indicators=NE.TRD.GNFS.ZS — WDI indicator timeseries grouped by country. Optional: &year=2020 for single-year cross-section.
- GET /api/wdi/indicators — List available WDI indicator codes with descriptions and categories.
- GET /api/wdi/rankings?indicator={code}&year=2020 — Country rankings for a specific WDI indicator.

### Unit Values

- GET /api/unit-values/{hs6}?year=2019 — Unit values (price per unit) for a product across all reporting countries. Reveals quality differentiation.
- GET /api/unit-values/search?q={query} — Search for products with unit value data.

### Commodity Prices

- GET /api/commodities/prices/search?q={query} — Search commodities by name. Returns commodity, category, unit, latest price.
- GET /api/commodities/prices/monthly?commodity={name}&start={YYYY-MM}&end={YYYY-MM} — Monthly nominal and real commodity price timeseries.
- GET /api/commodities/prices/annual?commodity={name} — Annual commodity price timeseries.
- GET /api/commodities/prices/sectors — Commodity sector overview: category, count, latest average price.
- GET /api/commodities/prices/correlation?category={name}&start_year=2000 — Price correlation matrix across commodities in a category.

### Agricultural Trade (FAO)

- GET /api/commodities/agri-trade/search?q={query} — Search FAO agricultural trade items.
- GET /api/commodities/agri-trade/{itemCode}/timeseries?area={areaCode} — Agricultural trade timeseries (exports, imports) for an FAO item and area.
- GET /api/commodities/agri-trade/{itemCode}/concentration — Export concentration for an agricultural item.
- GET /api/commodities/agri-trade/{itemCode}/map — Geographic distribution of trade for an agricultural item.

### Food Security

- GET /api/commodities/food-security/areas — List available FAO areas for food security analysis.
- GET /api/commodities/food-security/{areaCode} — Food security indicators for an area: import dependency, self-sufficiency, dietary energy supply.
- GET /api/commodities/food-security/compare?areas={codes} — Compare food security indicators across areas.
- GET /api/commodities/food-security/timeseries?areas={codes}&indicator={code} — Food security indicator timeseries.

### Value Chains

- GET /api/commodities/value-chains/areas — List available areas for value chain analysis.
- GET /api/commodities/value-chains/{areaCode} — Value chain data: value shares by industry, factor, and food value category.
- GET /api/commodities/value-chains/compare?areas={codes} — Compare value chain structures across areas.
- GET /api/commodities/value-chains/timeseries?areas={codes} — Value chain timeseries data.

### Trade Diagnostic

- GET /api/diagnostic/{iso3}?year=2024 — Comprehensive strategic trade diagnostic: health score, competitive threats, peer benchmarking, vulnerability analysis, and key findings.

### Supply Chain

- GET /api/supply-chain/compare?countries=USA,CHN&year=2021 — Compare supply chain vulnerability metrics across countries.

### Trade Flows & Visualization

- GET /api/trade-flows?year=2024 — Major bilateral trade flows for map visualization. Supports ?meta=years to list available years.
- GET /api/flows/demand?country={iso3}&year=2024 — Sankey diagram data: import demand flows grouped by budget share.
- GET /api/flows/supply-chain?country={iso3}&year=2024 — Sankey diagram data: supply chain flows by product section.

### Spatial & Time-lapse

- GET /api/spatial-analytics?country={iso3}&year=2024 — Geographic trade analytics with spatial patterns.
- GET /api/time-lapse?country={iso3} — Trade composition time-lapse data over all years.

### Trade Network

- GET /api/trade-network/evolution?countries={iso3_list} — Trade network evolution: centrality, community, and connectivity metrics over time.

### Forecasting

- GET /api/prediction/countries — List of countries available for trade forecasting.
- GET /api/prediction/commodities — List of commodities available for price forecasting.

### Impact Evaluation

- GET /api/impact?countries={iso3_list}&outcome=exports — Impact evaluation: compare trade outcomes across treatment/control country groups. outcome=exports|imports|balance|eci|hhi|growth.

### Live Trade Visualization

- GET /api/live/vessels — Live vessel positions (AIS data from Digitraffic/AISHUB, with simulated fallback).
- GET /api/live/shipping?year=2024&limit=50 — Top bilateral shipping routes with coordinates for animated visualization.
- GET /api/live/flights — Live cargo flight positions from OpenSky Network API.

### Intelligence Reports

- GET /api/intelligence?id={id} — Retrieve a specific AI-generated trade intelligence report.
- GET /api/intelligence — List all intelligence reports (id, title, summary, created_at).
- POST /api/intelligence — Generate a new AI-powered trade intelligence report.

### Utility Endpoints

- GET /api/guestbook?page=1 — Paginated guestbook comments (20 per page).
- POST /api/guestbook — Submit a guestbook comment (name, comment).
- POST /api/contact — Submit a contact message (name, email, message).
- POST /api/track — Track page view (path, referrer). Used for analytics.
- POST /api/crawl — Log AI crawler visits (path, bot_name, user_agent).

---

## Database Schema Overview

### trade.db (read-only, 19GB)

Primary trade database with all BACI, CEPII, FAOSTAT, WDI, commodity, EODB, and NTM data.

**Core tables:**
- countries (code, name, iso2, iso3) — 238 countries
- products (code, name, chapter, heading, section) — 6,800+ HS6 products across 21 sections
- country_year_product (country_code, year, product_code, export_value, import_value, export_qty, import_qty) — Main trade data table, ~170M rows
- bilateral_year (exporter_code, importer_code, year, total_value, export_value) — Bilateral trade totals
- country_year_totals (country_code, year, total_exports, total_imports, trade_balance) — Aggregated country totals

**Complexity & rankings:**
- eci_rankings (country_code, year, eci, eci_rank) — Economic Complexity Index
- pci_rankings (product_code, year, pci, pci_rank) — Product Complexity Index
- rca_matrix (country_code, product_code, year, rca) — Revealed Comparative Advantage values
- country_rankings (country_code, year, export_rank, import_rank) — Trade volume rankings
- country_hhi (country_code, year, hhi, normalized_hhi, num_products) — Export concentration
- country_growth (country_code, year, export_growth, import_growth) — Year-over-year growth
- product_rankings (product_code, year, total_trade, rank) — Product-level rankings
- product_growth (product_code, year, trade_growth) — Product trade growth

**Product space:**
- product_proximity (product_a, product_b, year, proximity) — Co-export proximity between product pairs

**Tariffs:**
- tariff_hs4_summary (reporter_code, hs4, year, mfn_simple_avg, mfn_min, mfn_max, n_hs6_lines, n_free_lines, n_dutiable_lines)
- tariff_elasticity (hs4, epsilon_hs4, zero, positive, missing)
- trade_elasticity (hs6, sigma, zero, positive) — HS6-level import demand elasticities
- pref_tariff_hs6 (reporter_code, hs6, partner, simple_avg, min_rate, max_rate, year)

**Trade costs:**
- escap_trade_costs (reporter, partner, year, sector, cost_pct) — ESCAP-World Bank bilateral trade costs

**Gravity model:**
- gravity_bilateral (iso3_o, iso3_d, year, dist, contig, comlang, colony, tradeflow_baci, gravity_residual, ...)

**Geopolitical dependency:**
- geodep (iso3_importer, hs6, year, first_odpt, share_odpt, import_dpt, c1-c4, dependent, sect_*) — Product-level import dependency
- geodep_country_summary (iso3_importer, year, total_products, critical_products, ...) — Country vulnerability summaries
- geodep_market_power (iso3_supplier, year, dominant_count, high_share_count, monopoly_count, avg_share)

**Unit values:**
- unit_values (reporter, product_code, year, avg_export_uv, avg_import_uv, median_export_uv, median_import_uv, num_export_partners, num_import_partners)

**Ease of Doing Business:**
- eodb (country_code, db_year, eodb_score, score_trading_borders, tb_time_export_doc, tb_cost_export_border, region, income_group, ...) — 202 countries, 2004-2020

**Non-Tariff Measures:**
- ntm_product (reporter, hs6, ntm_count, has_sps, has_tbt, ntm_types, ...) — 573K rows
- ntm_country (reporter, total_measures, total_products_covered, ...) — 125 countries

**Macroeconomic:**
- macro_gdp (country, year, gdp_val, gdp_cap, population, ...) — GDP and population data
- wdi_data (iso3, indicator, year, value) — World Development Indicators
- bop_flows / bop_indicators — Balance of payments data

**Commodity prices:**
- pink_sheet_monthly (commodity, date, price_nominal, price_real) — World Bank Pink Sheet monthly prices
- pink_sheet_annual (commodity, year, price_nominal) — Annual prices
- pink_sheet_categories (commodity, category, unit) — Commodity metadata

**Agricultural trade (FAO):**
- fao_trade (area_code, area, item_code, item, element, year, value) — FAO bilateral agricultural trade
- fao_trade_indicators — Food security indicators
- fao_value_shares — Value chain factor shares

**FRED/BLS:**
- fred_metadata (series_id, description) + fred_data (series_id, date, value) — Federal Reserve economic data
- bls_metadata (series_id, description) + bls_data (series_id, date, value) — Bureau of Labor Statistics data

**Historical:**
- historical_global (year, total_trade, ...) — 200+ years of global trade
- historical_trade (iso_o, iso_d, year, flow) — Historical bilateral flows

**Global trends:**
- global_trade_volume (year, trade_value_dollars, ...) — Aggregate world trade
- global_trade_by_stage (year, production_stage, ...) — Trade by BEC stage

### app.db (writable, auto-created)

- guestbook (id, name, comment, created_at)
- contact_messages (id, name, email, message, created_at)
- page_views (id, path, referrer, ip_hash, user_agent, created_at)
- intelligence_reports (id, title, summary, body, created_at)
- crawl_log (id, path, bot_name, user_agent, ip_hash, created_at)

---

## Example Queries

**"What does Bangladesh export?"**
Visit https://tradeweave.org/country/BGD or call GET /api/countries/BGD for summary, GET /api/countries/BGD/trade for the product treemap.

**"Top exports of Japan"**
Visit https://tradeweave.org/country/JPN or call GET /api/countries/JPN/trade?flow=export&year=2024

**"Who are China's top trading partners?"**
GET /api/countries/CHN/partners?flow=export&year=2024 for export destinations, or ?flow=import for import sources.

**"Bilateral trade between US and China over time"**
GET /api/bilateral/USA/CHN/timeseries — returns 30-year timeseries of forward (US->China), reverse (China->US), and balance.

**"Which countries export HS 854231 (integrated circuits)?"**
GET /api/products/854231/exporters?year=2024

**"How complex is Germany's economy?"**
GET /api/rankings/eci?year=2024 and find DEU, or GET /api/countries/DEU for its ECI and ECI rank.

**"What products is Vietnam gaining comparative advantage in?"**
GET /api/countries/VNM/rca-dynamics?year=2024&window=5 — shows rising stars and declining industries.

**"Trade cost between India and the US"**
GET /api/trade-costs/bilateral/IND?sector=manufacturing or visit https://tradeweave.org/trade-costs

**"Gravity model: is Brazil undertrading with anyone?"**
GET /api/gravity/potential?iso3=BRA&year=2020 — shows partners where actual trade is below gravity-predicted levels.

**"What tariffs does the EU charge on HS 0901 (coffee)?"**
GET /api/tariffs/0901/rates?year=2024

**"Compare USA, China, and Germany"**
GET /api/compare?countries=USA,CHN,DEU&year=2024 or visit https://tradeweave.org/compare

**"Historical trade of the British Empire"**
GET /api/historical/powers?year=1913 or visit https://tradeweave.org/historical

**"Food security of sub-Saharan Africa"**
Visit https://tradeweave.org/commodities/food-security or GET /api/commodities/food-security/{areaCode}

---

## Methodology Notes

### Economic Complexity Index (ECI)
Measures the diversity and sophistication of a country's export basket using the Hidalgo & Hausmann (2009) method of reflections. Countries that export many products that few other countries export score high. ECI is zero-centered: positive = more complex than average.

### Product Complexity Index (PCI)
The product analog of ECI. Products exported by few, highly complex countries score high. Reveals which products require sophisticated capabilities. PCI is also zero-centered and can be negative.

### Revealed Comparative Advantage (RCA)
Balassa's (1965) index: RCA = (country's share of product exports) / (world's share of product exports). RCA >= 1 means the country is specialized in that product. It is a dimensionless ratio, not a dollar value.

### Herfindahl-Hirschman Index (HHI)
Measures export concentration: HHI = sum of squared export shares across products. Ranges 0-1. HHI > 0.25 = highly concentrated; HHI < 0.1 = diversified.

### Grubel-Lloyd Index
Measures intra-industry trade between two countries: GL = 1 - |X-M|/(X+M). GL = 1 means fully two-way trade; GL = 0 means fully one-directional.

### Gravity Model
Predicts bilateral trade using GDP, distance, contiguity, common language, and colonial ties. Log-linear estimation: ln(Trade) = a + b*ln(GDP_o) + c*ln(GDP_d) - d*ln(Dist) + controls. Residuals reveal under/over-trading relative to gravity predictions.

### Import Demand Elasticity (sigma)
Measures how responsive imports are to price changes. |sigma| < 1 = inelastic (hard to substitute); |sigma| > 5 = highly elastic (easily substitutable). Used in the tariff simulator to estimate trade impacts.

### ESCAP Trade Costs
Bilateral trade costs as percentage of trade value, derived from the ESCAP-World Bank Trade Cost Database. Covers manufacturing and agriculture sectors, 1995-2018.

### Finger-Kreinin Export Similarity Index (ESI)
Measures how similar two countries' export baskets are: ESI = sum of min(share_i_product, share_j_product). ESI = 1 means identical export structures; ESI = 0 means no overlap.

### Technology Classification (Lall 2000)
Classifies products by technology intensity: Primary, Resource-Based, Low-Tech, Medium-Tech, High-Tech. Based on HS section mapping.

---

## Data Conventions

- BACI/CEPII trade values are stored in "thousands of USD" — multiply by 1000 for real USD
- FAOSTAT values are stored in "1000 USD" — same multiplier applies
- PCI is zero-centered and routinely negative — negative values are valid
- RCA is a dimensionless ratio — not a dollar amount
- ISO3 codes should be UPPERCASE (the API normalizes them, but UPPERCASE is preferred)
- Years available: 1995-2024 for BACI data, 1800-present for historical data
- Default year for most endpoints: 2024

## Data Sources

- BACI International Trade Database (CEPII) — http://www.cepii.fr/CEPII/en/bdd_modele/bdd_modele_item.asp?id=37
- UN Comtrade — https://comtrade.un.org/
- World Bank Open Data — https://data.worldbank.org/
- WITS/TRAINS Tariff Data — https://wits.worldbank.org/
- ESCAP-World Bank Trade Cost Database — https://databank.worldbank.org/source/escap-world-bank-international-trade-costs
- FRED (Federal Reserve Economic Data) — https://fred.stlouisfed.org/
- BLS (Bureau of Labor Statistics) — https://www.bls.gov/
- FAOSTAT — https://www.fao.org/faostat/
- Atlas of Economic Complexity (Harvard) — https://atlas.cid.harvard.edu/
- World Bank Pink Sheet (Commodity Prices) — https://www.worldbank.org/en/research/commodity-markets
- Geodep — CEPII Geopolitical Dependency Database

## Contact

Built by Mazharul Hossen. For questions or data access, visit https://tradeweave.org/about.