# Beta 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.

> Analyze international trade patterns by accessing comprehensive goods and services trade statistics, time series data, and trade indicators across countries and product classifications. Track trade flows using standardized HS and EBOPS product codes to compare performance metrics and coverage across different markets and time periods.

**Category:** Government & Public Data | **Website:** [beta.trademap.org/](https://beta.trademap.org/) | **Docs:** [parse.bot/marketplace/4d7aa15d-7d20-47b2-8fd7-cc3ecb06fb97/beta-trademap-org-api](https://parse.bot/marketplace/4d7aa15d-7d20-47b2-8fd7-cc3ecb06fb97/beta-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-beta-trademap-org-api-4d7aa15d/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_countries

Returns all countries and territories recognized by Trade Map with their data coverage periods for goods (yearly, quarterly, monthly) and services. Each country includes first/last available period per data frequency. The full list is returned in a single response with no pagination.

**Estimated cost:** Metered

_No parameters required._

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

### get_country_groups

Returns all country groupings recognized by Trade Map: economic groups (BRICS, OECD, LDCs), geographic regions (Africa, Asia), customs unions (EU, MERCOSUR, ASEAN), and intergovernmental organisations. Single-page response.

**Estimated cost:** Metered

_No parameters required._

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

### get_coverage

Returns data coverage information showing how many countries have reported data and the latest available period, broken down by frequency (yearly, quarterly, monthly). Available for goods or services.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `data_type` | string | No | Type of trade data to check coverage for. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-beta-trademap-org-api-4d7aa15d/get_coverage \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data_type":"<string>"}'
```

### get_products_hs

Returns all HS (Harmonized System) product codes with labels. Includes 2-digit chapters, 4-digit headings, and 6-digit subheadings across all HS revisions. Single-page response returning ~8000 codes.

**Estimated cost:** Metered

_No parameters required._

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

### get_services_ebops

Returns EBOPS (Extended Balance of Payments Services) classification codes used for services trade data. Each code includes a display code and maximum hierarchy level. Single-page response.

**Estimated cost:** Metered

_No parameters required._

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

### goods_time_series

Returns yearly goods trade time series data with pagination. Can break down by HS product codes or by partner country. Each record contains period/value pairs over the requested year range. Requires a specific reporter country code (World/000 is not supported as reporter). Paginated with configurable page size up to 500.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `by` | string | No | Breakdown dimension for the time series. |
| `country` | string | No | Reporter country code (3-digit). Must be a specific country, not 000 (World). |
| `currency` | string | No | Currency for trade values. |
| `direct_mirror` | string | No | Data source type. |
| `hs_level` | string | No | HS classification detail level. |
| `indicator` | string | No | Trade indicator type. |
| `page` | integer | No | Page number for paginated results. |
| `page_size` | string | No | Number of records per page (max 500). |
| `partner` | string | No | Partner country code. 000 means all partners (World). |
| `period_from` | string | No | Start year of the time series range. |
| `period_to` | string | No | End year of the time series range. |
| `product` | string | No | HS product code to filter by, or ALL for all products. |
| `sort_by` | string | No | Sort by year value. Defaults to the period_to value. |
| `sort_dir` | string | No | Sort direction for results. |
| `trade_flow` | string | No | Direction of trade. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-beta-trademap-org-api-4d7aa15d/goods_time_series \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"by":"<string>","country":"<string>","currency":"<string>","direct_mirror":"<string>","hs_level":"<string>","indicator":"<string>","page":"<integer>","page_size":"<string>","partner":"<string>","period_from":"<string>","period_to":"<string>","product":"<string>","sort_by":"<string>","sort_dir":"<string>","trade_flow":"<string>"}'
```

### goods_trade_indicators

Returns goods trade indicators (value, balance, growth rates) by HS product or partner country for the most recent reference year. Available indicators: VAL (trade value), BAL (trade balance), GV5 (5-year growth), GV2 (2-year growth), GV5W (world 5-year growth). Paginated.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `by` | string | No | Breakdown dimension for indicators. |
| `country` | string | No | Reporter country code (3-digit). Must be a specific country, not 000. |
| `currency` | string | No | Currency for trade values. |
| `direct_mirror` | string | No | Data source type. |
| `hs_level` | string | No | HS classification detail level. |
| `indicators` | string | No | Comma-separated list of indicator codes to include: VAL, BAL, GV5, GV2, GV5W. |
| `page` | integer | No | Page number for paginated results. |
| `page_size` | string | No | Number of records per page (max 500). |
| `partner` | string | No | Partner country code. 000 means all partners (World). |
| `product` | string | No | HS product code to filter by, or ALL for all products. |
| `sort_by` | string | No | Sort by indicator code. |
| `sort_dir` | string | No | Sort direction for results. |
| `trade_flow` | string | No | Direction of trade. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-beta-trademap-org-api-4d7aa15d/goods_trade_indicators \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"by":"<string>","country":"<string>","currency":"<string>","direct_mirror":"<string>","hs_level":"<string>","indicators":"<string>","page":"<integer>","page_size":"<string>","partner":"<string>","product":"<string>","sort_by":"<string>","sort_dir":"<string>","trade_flow":"<string>"}'
```

### services_time_series

Returns yearly services trade time series data with pagination. Can break down by partner country or EBOPS service category. Each record contains period/value pairs over the requested year range. Requires a specific reporter country code. Note: sort_dir=asc may cause timeouts on large datasets.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `by` | string | No | Breakdown dimension for the time series. |
| `country` | string | No | Reporter country code (3-digit). Must be a specific country, not 000. |
| `currency` | string | No | Currency for trade values. |
| `page` | integer | No | Page number for paginated results. |
| `page_size` | string | No | Number of records per page (max 500). |
| `period_from` | string | No | Start year of the time series range. |
| `period_to` | string | No | End year of the time series range. |
| `service` | string | No | EBOPS service code to filter by, or ALL for all services. |
| `sort_by` | string | No | Sort by year value. Defaults to the period_to value. |
| `sort_dir` | string | No | Sort direction for results. desc recommended; asc may timeout on large datasets. |
| `trade_flow` | string | No | Direction of trade. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-beta-trademap-org-api-4d7aa15d/services_time_series \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"by":"<string>","country":"<string>","currency":"<string>","page":"<integer>","page_size":"<string>","period_from":"<string>","period_to":"<string>","service":"<string>","sort_by":"<string>","sort_dir":"<string>","trade_flow":"<string>"}'
```