# Trademap — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access comprehensive global trade statistics including bilateral trade flows, product exports by country, and historical trade indicators to analyze international commerce trends. Monitor trade data availability and retrieve time series information to track how specific products and countries perform in the global market.

**Category:** Government & Public Data | **Website:** [trademap.org/](https://trademap.org/) | **Docs:** [parse.bot/marketplace/df8c8eb3-a670-4480-bf60-427de2ff2863/trademap-org-api](https://parse.bot/marketplace/df8c8eb3-a670-4480-bf60-427de2ff2863/trademap-org-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-trademap-org-api-df8c8eb3/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_bilateral_trade

Retrieve bilateral trade data between two specific countries for a product. Returns product-level breakdown of trade flows showing reporter imports from partner, partner exports to world, and reporter imports from world across recent years. Each record includes the product code, label, and value columns for the bilateral relationship.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `hs_code` | string | No | HS product code (e.g. '8471' for computers). Use 'TOTAL' for all products aggregated. |
| `partner_code` | string | No | Partner country numeric code (e.g. '156' for China, '842' for USA). |
| `reporter_code` | string | No | Reporter country numeric code (e.g. '842' for USA, '276' for Germany). |
| `trade_flow` | string | No | Trade flow direction. '2' for Export, '4' for Import. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-trademap-org-api-df8c8eb3/get_bilateral_trade \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hs_code":"<string>","partner_code":"<string>","reporter_code":"<string>","trade_flow":"<string>"}'
```

### get_data_availability

Retrieve data availability status for all countries across recent years. Returns a numeric availability code per country per year: 0 = no data, 1 = mirror data only, 2 = reported data available. No input parameters required.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-trademap-org-api-df8c8eb3/get_data_availability \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_products_by_country

Retrieve products (HS codes) traded by a specific country with yearly time series values. Returns product codes, labels, and import/export values across recent years. Each record includes the HS code, product label text, and value columns per year. Use hs_level to control digit granularity (2, 4, or 6).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `hs_level` | string | No | HS code digit level for product granularity. '2' for chapters, '4' for headings, '6' for subheadings. |
| `reporter_code` | string | No | Reporter country numeric code (e.g. '842' for USA, '276' for Germany, '156' for China). |
| `trade_flow` | string | No | Trade flow direction. '2' for Export, '4' for Import. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-trademap-org-api-df8c8eb3/get_products_by_country \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hs_level":"<string>","reporter_code":"<string>","trade_flow":"<string>"}'
```

### get_trade_indicators

Retrieve trade indicators (export value, trade balance, growth, share, concentration) for a specific product and reporter country. Returns a list of exporting countries ranked by export value. Each record includes the exporter name, value exported, trade balance, annual growth rates, world export share percentage, average distance of importing countries, and concentration index. Use trade_flow to switch between export and import perspectives. Paginates as a single page containing all ranked countries.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `hs_code` | string | No | HS product code (e.g. '8471' for computers). Use 'TOTAL' for all products aggregated. |
| `partner_code` | string | No | Partner country numeric code to filter results. Empty string for all partners. |
| `reporter_code` | string | No | Reporter country numeric code (e.g. '842' for USA, '276' for Germany, '156' for China). |
| `trade_flow` | string | No | Trade flow direction. '2' for Export, '4' for Import. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-trademap-org-api-df8c8eb3/get_trade_indicators \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hs_code":"<string>","partner_code":"<string>","reporter_code":"<string>","trade_flow":"<string>"}'
```

### get_yearly_time_series

Retrieve yearly trade value time series for a specific product and reporter country. Returns exported/imported values across multiple recent years for top trading countries. Each record includes the country name and value columns for each available year. Useful for trend analysis over a 5-year window.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `hs_code` | string | No | HS product code (e.g. '8471' for computers). Use 'TOTAL' for all products aggregated. |
| `partner_code` | string | No | Partner country numeric code to filter results. Empty string for all partners. |
| `reporter_code` | string | No | Reporter country numeric code (e.g. '842' for USA, '276' for Germany, '156' for China). |
| `trade_flow` | string | No | Trade flow direction. '2' for Export, '4' for Import. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-trademap-org-api-df8c8eb3/get_yearly_time_series \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hs_code":"<string>","partner_code":"<string>","reporter_code":"<string>","trade_flow":"<string>"}'
```