API使用方法ガイド

Proプランでは、REST API経由でプログラムからデータを取得できます。自社システムへの統合や、自動化されたデータ取得が可能です。

Proプラン限定機能

APIアクセスはProプラン（月額9,800円）でご利用いただけます。月間10,000リクエストまで対応しています。

APIキーの取得

ログイン後、設定画面（/settings）にアクセス
「APIキー」セクションで「新規作成」をクリック
キー名を入力して作成
表示されたAPIキーをコピーして保存

重要

APIキーは作成時のみ表示されます。必ず安全な場所に保存してください。APIキーは他人と共有しないでください。

認証方法

すべてのAPIリクエストには、AuthorizationヘッダーでAPIキーを送信する必要があります。

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

レート制限

項目	制限
月間リクエスト数	10,000リクエスト
1秒あたりのリクエスト数	10リクエスト

制限を超えた場合、429 Too Many Requestsエラーが返されます。使用量はレスポンスのusageフィールドで確認できます。

エンドポイント一覧

GET /api/v1/trade/search

貿易データを検索します。

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"

パラメータ	型	説明
`hsCodes`	string	HSコード（カンマ区切りで複数指定可）
`countryCodes`	string	国コード（カンマ区切りで複数指定可）
`startYear`	number	開始年
`endYear`	number	終了年
`exportImport`	string	E（輸出）または I（輸入）
`page`	number	ページ番号（デフォルト: 1）
`perPage`	number	1ページあたりの件数（最大100）

GET /api/v1/trade/statistics

統計データを取得します。

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

パラメータ	型	説明
`groupBy`	string	country または hs_code

レスポンス形式

すべてのレスポンスはJSON形式です。

{
  "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
  }
}

デュアル数量単位について

デュアル単位が定義された HS コード（例: 石油製品 KL + KG）の場合、API は quantity_1 (第1単位の数量) と quantity_2 (第2単位の数量) を単位ラベル (quantity_unit_1 / quantity_unit_2) と合わせて返します。単一単位品目では quantity_2 のみが入り quantity_1 は null になります。リクエスト時の unitPref パラメータ (unit_1 / unit_2 / both、デフォルト both) で描画優先単位を指定できます。prediction エンドポイントだけは unitPref をサーバーで尊重し、選択された単位で 1 本のみ ARIMA 予測を計算します。

エラーレスポンス

ステータスコード	説明
`400`	パラメータが不正
`401`	APIキーが無効、または期限切れ
`429`	レート制限超過
`500`	サーバーエラー

SDK・ライブラリ

現在、公式SDKは提供していません。HTTPクライアントを使用して直接APIを呼び出してください。

Pythonでの例

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での例

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}`);