# Japan Trade Statistics (Customs, HS x Country, Monthly) (`jpopendata/japan-trade-stats`) Actor

Monthly Japanese import/export statistics by HS commodity code and partner country, straight from the official Japan Customs (Ministry of Finance) trade statistics database. English field schema and country names, values in JPY, quantities with units, year-to-date cumulatives, source attribution…

- **URL**: https://apify.com/jpopendata/japan-trade-stats.md
- **Developed by:** [JP Open Data](https://apify.com/jpopendata) (community)
- **Categories:** Lead generation, Automation
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Japan Trade Statistics (Customs, HS × Country, Monthly)

**Monthly Japanese import/export statistics by HS commodity code and partner country — straight from Japan Customs, no API key, no account.**

This Actor queries the official trade statistics database of Japan Customs (Ministry of Finance, customs.go.jp) and returns the Commodity-by-Country table (普通貿易統計 品別国別表) as clean JSON: 9-digit statistical code, derived 6-digit HS subheading, partner country, quantities with units, trade value in actual JPY, and year-to-date cumulatives. Think of it as the Japanese counterpart of USITC DataWeb-style tooling — data back to 1988, published monthly.

> **Unofficial tool.** Not affiliated with or endorsed by Japan Customs or the Ministry of Finance. Source: 税関ホームページ（財務省貿易統計）. The customs site's terms of use expressly permit reproduction, adaptation, and **commercial use** with attribution (「商用利用も可能です」) — the attribution is embedded in the `license` string of every output record.

***

### Who is this for?

- **Trade intelligence and policy analysts** — measure tariff and trade-friction impact on specific commodity flows, monthly, at HS-code granularity.
- **Sourcing and commodity research teams** — who supplies Japan with what, and where Japanese exports go, tracked over time.
- **Economists, journalists, and data teams** — a scriptable alternative to a Japanese-first search interface, with values already converted from the source's 1000-yen units to actual JPY.

### Sample output (dataset item)

```json
{
  "period": "2026-06",
  "tradeType": "export",
  "hsCode": "2204.10-000",
  "hs6": "220410",
  "countryCode": "304",
  "country": "USA",
  "quantityUnit1": "",
  "quantityUnit2": "L",
  "quantity1": null,
  "quantity2": 123456,
  "valueJpy": 245678000,
  "ytdQuantity2": 654321,
  "ytdValueJpy": 1234567000,
  "source": "税関ホームページ（財務省貿易統計）",
  "sourceUrl": "https://www.customs.go.jp/toukei/info/index.htm",
  "license": "税関ホームページ利用規約 (kiyaku.htm) — 商用利用可・出典記載 / 出典: 税関ホームページ",
  "retrievedAt": "2026-08-25T09:12:44Z"
}
```

Country names come from the source's own English interface (customs' abbreviations, e.g. `"USA"`, `"NICARAG"`); `null` quantities are the source's `-` (not published / no trade), passed through honestly rather than zero-filled.

### Input example

```json
{
  "tradeType": "import",
  "period": "2026-01..2026-06",
  "hsCodePrefix": "0901",
  "countryCode": "213"
}
```

- `hsCodePrefix` — **required**: 2/4/6-digit HS prefix or full 9-digit Japanese statistical code. Full-month dumps of everything are deliberately unsupported.
- `period` — a month (`YYYY-MM`), a range (max 6 months per run), or empty for the latest published month, discovered automatically.
- `countryCode` — optional 3-digit customs country code ([official code list](https://www.customs.go.jp/toukei/sankou/code/country_e.htm)).

### Pricing

Pay per result — see the pricing tab. A single commodity × country × month query is a handful of rows; a 6-month panel of an HS4 chapter across all partners is typically a few thousand.

### FAQ

**Where does the data come from?**
From the official Japan Customs trade statistics search system on customs.go.jp — retrieved directly from the customs servlet in its English mode, so column semantics and country names are the source's own English publication, not our translation. No e-Stat account, no appId, no API key.

**Is this an official government service?**
No. **Unofficial**, independently built and maintained. The customs terms of use permit commercial reuse with attribution; the required 出典 statement is embedded in every record.

**How fresh is the data?**
Monthly, with a publication lag of roughly two months (e.g., June figures available in late August). Leave `period` empty and the Actor finds the latest published month itself. Data reaches back to 1988. Note that recently published months may be provisional figures subject to later revision by customs.

**Why is `hsCodePrefix` required?**
Two honest reasons: the upstream caps one query at 3,000 rows, and we don't do unbounded full dumps of public servers as a matter of design. If your query would exceed the cap, the Actor fails **before** downloading, with a message telling you to narrow the HS prefix or add a country filter.

**Are commodity descriptions included?**
No — the commodity-by-country table publishes codes only; descriptions live in a separate tariff table upstream. `hs6` gives you the international 6-digit subheading to join against any standard HS nomenclature you already use.

**Any privacy concerns?**
None by construction: this is aggregate national statistics. Automated tests still assert no personal-data-shaped strings and full source attribution on every record.

**What about server load?**
Two polite requests per month queried (search + CSV retrieval), ≥1.5 s apart, exponential backoff, hard request budget, no rate-limit evasion. Max 6 months per run keeps single runs modest by design.

### Search terms this Actor answers

Japan trade statistics API · Japan import export data by HS code · Japan customs data English · Japan trade data by country · Japanese export statistics monthly · HS code Japan imports · USITC DataWeb Japan equivalent · Japan tariff impact data

### More Japan public-data Actors by the same developer

- **Japan Government Tenders & Awards** — tender notices and award results from the kkj.go.jp portal.
- **Japan Medical Facilities** — every registered hospital, clinic, dental clinic, and pharmacy (MHLW open data).
- **Japan Care Facilities** — long-term care providers across 35 service types (MHLW open data, CC BY).
- **Japan Government Subsidies & Grants** — open subsidy calls from the official jGrants API.
- **Japan Renewable Energy FIT/FIP Facilities** — METI-certified renewable installations, privacy-safe schema.
- **Japan Financial Licenses & Registrations** — FSA-licensed banks, securities firms, crypto exchanges and more.
- **Japan Construction & Real-Estate Licenses** — licensed contractors and brokers from MLIT's register.

***

*Data source: 税関ホームページ（財務省貿易統計）— https://www.customs.go.jp/toukei/info/index.htm . Terms: https://www.customs.go.jp/kiyaku.htm (commercial use permitted, attribution required — embedded in every record).*

# Actor input Schema

## `tradeType` (type: `string`):

Exports from Japan or imports into Japan.

## `period` (type: `string`):

A month `YYYY-MM` (e.g. `2026-06`) or an inclusive range `YYYY-MM..YYYY-MM` (max 6 months per run; each month costs 2 polite upstream requests). Leave empty to fetch the latest published month automatically. Data reaches back to 1988; recent months are published with roughly a 2-month lag.

## `hsCodePrefix` (type: `string`):

REQUIRED. HS commodity code prefix: 2 digits (chapter, e.g. `22` beverages), 4 digits (heading, e.g. `2204` wine), 6 digits (subheading), or the full 9-digit Japanese statistical code. Dots and dashes are tolerated (`2204.10-000`). Full-month dumps are deliberately unsupported — the upstream CSV endpoint caps one query at 3000 rows.

## `countryCode` (type: `string`):

Optional 3-digit customs country code (e.g. `304` = USA, `105` = China, `103` = South Korea). Leave empty for all partner countries. Code list: https://www.customs.go.jp/toukei/sankou/code/country\_e.htm

## `maxItems` (type: `integer`):

Maximum number of records to output across all requested months. The upstream CSV always carries the full result set for a month (up to 3000 rows); this truncates the output client-side.

## `maxApiRequests` (type: `integer`):

Hard safety cap on upstream requests in one run. A run needs 2 requests per month (search + CSV download), plus 1 when `period` is empty (latest-month probe); headroom only covers polite retries after 429/5xx. Politeness (1 connection, >= 1.5 s spacing, exponential backoff) is enforced in code.

## `proxyConfiguration` (type: `object`):

Apify proxy settings. Default is NO proxy (direct connection). The actor backs off exponentially on 429/5xx and fails visibly on a persistent block — it never attempts rate-limit evasion.

## Actor input object example

```json
{
  "tradeType": "export",
  "period": "2026-06",
  "hsCodePrefix": "2204",
  "countryCode": "304",
  "maxItems": 1000,
  "maxApiRequests": 8,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `records` (type: `string`):

Structured records with source attribution (source, sourceUrl, license, retrievedAt) on every item.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("jpopendata/japan-trade-stats").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("jpopendata/japan-trade-stats").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call jpopendata/japan-trade-stats --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jpopendata/japan-trade-stats"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Qz9f9WkTKSgeUAGLA/builds/p3lVu6P91PnYvpKd0/openapi.json