API Usage Guide

With the Pro plan, you can retrieve data programmatically via REST API. Integration with your systems and automated data retrieval are possible.

Pro Plan Only

API access is available with the Pro plan (9,800 JPY/month). Up to 10,000 requests per month are supported.

Getting an API Key

After logging in, go to the settings page (/settings)
Click "Create New" in the "API Key" section
Enter a key name and create
Copy and save the displayed API key

Important

The API key is only displayed once when created. Be sure to save it in a secure location. Do not share your API key with others.

Authentication

All API requests require sending the API key via the Authorization header.

curl -H "Authorization: Bearer kro_YOUR_API_KEY" \
  https://kouro.info/api/v1/trade/search

Rate Limits

Item	Limit
Monthly requests	10,000 requests
Requests per second	10 requests

When limits are exceeded, a 429 Too Many Requests error is returned. Usage can be checked in the usage field of the response.

Endpoints

GET /api/v1/trade/search

Search trade data.

curl -H "Authorization: Bearer kro_YOUR_API_KEY" \
  "https://kouro.info/api/v1/trade/search?hsCodes=8703&startYear=2024&endYear=2024&page=1&perPage=50"

Parameter	Type	Description
`hsCodes`	string	HS code (multiple codes separated by commas)
`countryCodes`	string	Country code (multiple codes separated by commas)
`startYear`	number	Start year
`endYear`	number	End year
`exportImport`	string	E (export) or I (import)
`page`	number	Page number (default: 1)
`perPage`	number	Items per page (max 100)

GET /api/v1/trade/statistics

Retrieve statistical data.

curl -H "Authorization: Bearer kro_YOUR_API_KEY" \
  "https://kouro.info/api/v1/trade/statistics?startYear=2024&groupBy=country"

Parameter	Type	Description
`groupBy`	string	country or hs_code

Response Format

All responses are in JSON format.

{
  "data": [
    {
      "year": 2024,
      "month": 1,
      "hsCode": "271012181",
      "countryCode": "USA",
      "countryName": "アメリカ",
      "exportImport": "E",
      "quantity_1": 1234,
      "quantity_unit_1": "KL",
      "quantity_2": 1050000,
      "quantity_unit_2": "KG",
      "amount": 5000000000
    },
    {
      "year": 2024,
      "month": 1,
      "hsCode": "09022210",
      "countryCode": "LKA",
      "countryName": "スリランカ",
      "exportImport": "I",
      "quantity_1": null,
      "quantity_unit_1": null,
      "quantity_2": 800,
      "quantity_unit_2": "KG",
      "amount": 120000
    }
  ],
  "total": 1234,
  "page": 1,
  "perPage": 50,
  "usage": {
    "monthlyLimit": 10000,
    "currentMonthUsage": 45,
    "remaining": 9955
  }
}

Dual quantity units

For HS codes defined with two units (e.g. petroleum products: KL + KG), the API returns both quantity_1 (primary unit) and quantity_2 (secondary unit) with their unit labels (quantity_unit_1, quantity_unit_2). Single-unit items only populate quantity_2 (quantity_1 is null). Use the unitPref request parameter (unit_1 | unit_2 | both, default both) to control rendering; the prediction endpoint also uses unitPref server-side to compute a single ARIMA series on the chosen unit.

Error Responses

Status Code	Description
`400`	Invalid parameters
`401`	Invalid or expired API key
`429`	Rate limit exceeded
`500`	Server error

SDKs & Libraries

Official SDKs are not currently available. Please call the API directly using an HTTP client.

Python Example

import requests

API_KEY = "kro_YOUR_API_KEY"
BASE_URL = "https://kouro.info/api/v1"

headers = {"Authorization": f"Bearer {API_KEY}"}
params = {"hsCodes": "8703", "startYear": 2024}

response = requests.get(
    f"{BASE_URL}/trade/search",
    headers=headers,
    params=params
)

data = response.json()
print(f"Total records: {data['total']}")

JavaScript Example

const API_KEY = 'kro_YOUR_API_KEY';
const BASE_URL = 'https://kouro.info/api/v1';

const response = await fetch(
  `${BASE_URL}/trade/search?hsCodes=8703&startYear=2024`,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

const data = await response.json();
console.log(`Total records: ${data.total}`);