# Trademap — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/trademap/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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.beta.paywithlocus.com/api/wrapped/credits/trademap/get-bilateral-trade \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/trademap/get-data-availability \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/trademap/get-products-by-country \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/trademap/get-trade-indicators \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/trademap/get-yearly-time-series \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"hs_code":"<string>","partner_code":"<string>","reporter_code":"<string>","trade_flow":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.