API

No key, no account

There is nothing to sign up for: send a request. The API sets no cookie and does not store what you send to a calculation. A limit for each sender takes the place of a key.

The limit

Each sender may make a burst of up to 60 requests, refilled at 60 a minute. A sender is an IP address (for IPv6, its /64 network). Every answer says where you stand in its headers: RateLimit-Limit is the size of a full bucket, RateLimit-Remaining what is left, RateLimit-Reset the seconds until it is full again. When it is empty the answer is 429 with a Retry-After header: the seconds to wait before asking again.

A page of rows counts as more than one request: one for each 1000 rows it asks for. A request may ask for at most 5000 rows (limit), and offset skips rows. The body of a calculation may be up to 256 KB and must be JSON.

バケットに1回分しかない利用者が2回目のリクエストで受け取る応答：

curl 'https://chukoudan.com/v1/tools'

HTTP 429
access-control-allow-origin: *
cache-control: no-store
content-type: application/json
ratelimit-limit: 1
ratelimit-remaining: 0
ratelimit-reset: 60
retry-after: 60

{
  "issues": [
    {
      "path": "",
      "code": "api.rate_limited",
      "values": {},
      "message": "请求太频繁；请按响应头 Retry-After 给出的秒数之后再试。 / Too many requests; try again after the number of seconds in the Retry-After header."
    }
  ],
  "provenance": {
    "api": "v1",
    "site": "chukoudan.com",
    "generated_at": "2026-10-07T04:00:00.000Z",
    "language": "zh-CN",
    "source_line": "来源：出口单 chukoudan.com · 生成于 2026-10-07",
    "notice": "本站非官方渠道，仅供参考，以官方公布为准。",
    "datasets": [],
    "license": {
      "status": "approved",
      "ours": "dataset.license.ours",
      "underlying": "dataset.license.underlying"
    }
  }
}

キャッシュ

保存してよい応答には ETag と Cache-Control が付きます。データセットの一覧、バージョン一覧、現行バージョンの行は 1 分、ツールの説明は 5 分、現行でないバージョンの行は 1 日です。If-None-Match を付けて送り、内容に変更がなければ本文なしの 304 が返ります（制限には数えられます）。エラーと計算結果はすべて no-store です。

From a browser

Any website may call these routes from a visitor's browser (GET and POST, no credentials). Calculations accept JSON only: a request of another content type is refused with 415.

What an answer looks like

A calculation returns tool (its id), outputs (each figure by name), steps (the worked example, line by line), warnings and provenance. An input that is refused returns 400 with issues instead of outputs. Each step and warning carries its copy key (like cbm.more_than_20gp) and the values that fill it. For every tool (tuishui, baojia, fx-cost, cbm, container-load, fx-convert, unit-convert and maitou) each also carries a message: one ready sentence with the figures filled in, in the language chosen with lang. Where there is a message, use it as it is and do not work the figures out again; where there is none (a sentence that cannot be made whole), write from the key and the values.

Figures

Every figure is tagged so you know how to write it, and numbers are exact decimal strings, never floating point. A quantity has value, unit and sometimes places (keep that many decimals: pad with zeros to it, do not round again); money has amount and currency; ratio is a fraction (0.13 is 13 %); rate says per units of base cost value units of quote; count, code (a token from a fixed list) and date complete the set.

Where the figures come from

Every answer, errors included, carries provenance: api (the version, v1), site, generated_at, language, source_line (one credit line to quote as it is: this site, and the day of the data), datasets (each dataset version the answer drew on, with its published_at day, its origin and a source line you can cite) and license. Adding lang=zh-CN, en, ja or ko to any request chooses the language of each message, of source_line and of the source lines, and changes no figure; without lang they are in Chinese. The license holds its status and copy keys, not words: the words are on the data sources and licence page.

Errors

An error answer has issues (each with path, code, values and a message: one sentence in Chinese and English together, whatever lang says) and provenance. 400: the input was refused (path says which field, code why; codes are copy keys); 404: no such tool, dataset or version; 413: the body is too big; 415: it is not JSON; 429: over the limit; 500: something failed on our side, and the answer says nothing more about the cause.

A calculation

POST a tool's inputs to /v1/tools/ID/compute. This example asks for the cubic metres of 450 cartons of 60 × 40 × 50 cm at 18 kg, shipped LCL. The same inputs on the CBM page give the same figures.

リクエスト

curl -X POST 'https://chukoudan.com/v1/tools/cbm/compute' -H 'content-type: application/json' -d '{"inputs":{"cartons":[{"length":"60","width":"40","height":"50","grossWeight":"18","quantity":"450"}],"lengthUnit":"cm","weightUnit":"kg","mode":"lcl"}}'

レスポンス

HTTP 200
access-control-allow-origin: *
cache-control: no-store
content-type: application/json
ratelimit-limit: 60
ratelimit-remaining: 59
ratelimit-reset: 1

{
  "tool": "cbm",
  "outputs": {
    "totalVolume": {
      "kind": "quantity",
      "value": "54",
      "unit": "m3"
    },
    "totalGrossWeight": {
      "kind": "quantity",
      "value": "8100",
      "unit": "kg"
    },
    "perCartonVolume": {
      "kind": "quantity",
      "value": "0.12",
      "unit": "m3"
    },
    "airVolumetric": {
      "kind": "quantity",
      "value": "9000",
      "unit": "kg"
    },
    "airChargeable": {
      "kind": "quantity",
      "value": "9000",
      "unit": "kg"
    },
    "airBy": {
      "kind": "code",
      "value": "volume"
    },
    "expressVolumetric": {
      "kind": "quantity",
      "value": "10800",
      "unit": "kg"
    },
    "expressChargeable": {
      "kind": "quantity",
      "value": "10800",
      "unit": "kg"
    },
    "expressBy": {
      "kind": "code",
      "value": "volume"
    },
    "lclChargeable": {
      "kind": "quantity",
      "value": "54",
      "unit": "m3"
    },
    "lclBy": {
      "kind": "code",
      "value": "volume"
    },
    "chargeable": {
      "kind": "quantity",
      "value": "54",
      "unit": "m3"
    }
  },
  "steps": [
    {
      "id": "cbm.row",
      "values": {
        "row": {
          "kind": "count",
          "value": "1"
        },
        "length": {
          "kind": "quantity",
          "value": "60",
          "unit": "cm"
        },
        "width": {
          "kind": "quantity",
          "value": "40",
          "unit": "cm"
        },
        "height": {
          "kind": "quantity",
          "value": "50",
          "unit": "cm"
        },
        "quantity": {
          "kind": "count",
          "value": "450"
        },
        "cartonVolume": {
          "kind": "quantity",
          "value": "120000",
          "unit": "cm3"
        },
        "perCartonVolume": {
          "kind": "quantity",
          "value": "0.12",
          "unit": "m3"
        },
        "volume": {
          "kind": "quantity",
          "value": "54",
          "unit": "m3"
        },
        "airVolumetric": {
          "kind": "quantity",
          "value": "9000",
          "unit": "kg"
        },
        "airDivisor": {
          "kind": "count",
          "value": "6000",
          "grouping": false
        },
        "expressVolumetric": {
          "kind": "quantity",
          "value": "10800",
          "unit": "kg"
        },
        "expressDivisor": {
          "kind": "count",
          "value": "5000",
          "grouping": false
        },
        "grossWeight": {
          "kind": "quantity",
          "value": "18",
          "unit": "kg"
        },
        "weight": {
          "kind": "quantity",
          "value": "8100",
          "unit": "kg"
        }
      },
      "message": "箱规 1：60 cm × 40 cm × 50 cm = 0.12 m3 × 450 箱 = 54 m3\n18 kg × 450 = 8100 kg\n120000 cm3 ÷ 6000 × 450 = 9000 kg（空运），÷ 5000 = 10800 kg（快递）"
    },
    {
      "id": "cbm.total",
      "values": {
        "totalVolume": {
          "kind": "quantity",
          "value": "54",
          "unit": "m3"
        },
        "totalGrossWeight": {
          "kind": "quantity",
          "value": "8100",
          "unit": "kg"
        },
        "gp20Share": {
          "kind": "ratio",
          "value": "1.6307"
        }
      },
      "message": "合计：总体积 54 m3，总毛重 8100 kg"
    },
    {
      "id": "cbm.lcl",
      "values": {
        "volume": {
          "kind": "quantity",
          "value": "54",
          "unit": "m3"
        },
        "weight": {
          "kind": "quantity",
          "value": "8.1",
          "unit": "t",
          "places": 3
        },
        "chargeable": {
          "kind": "quantity",
          "value": "54",
          "unit": "m3"
        },
        "by": {
          "kind": "code",
          "value": "volume"
        }
      },
      "message": "拼箱计费吨 W/M：较大值（54 m3，8.100 t）= 54 m3，按体积"
    },
    {
      "id": "cbm.air",
      "values": {
        "volumetric": {
          "kind": "quantity",
          "value": "9000",
          "unit": "kg"
        },
        "weight": {
          "kind": "quantity",
          "value": "8100",
          "unit": "kg"
        },
        "chargeable": {
          "kind": "quantity",
          "value": "9000",
          "unit": "kg"
        },
        "by": {
          "kind": "code",
          "value": "volume"
        }
      },
      "message": "空运计费重：较大值（8100 kg，9000 kg）= 9000 kg，按体积"
    },
    {
      "id": "cbm.express",
      "values": {
        "volumetric": {
          "kind": "quantity",
          "value": "10800",
          "unit": "kg"
        },
        "weight": {
          "kind": "quantity",
          "value": "8100",
          "unit": "kg"
        },
        "chargeable": {
          "kind": "quantity",
          "value": "10800",
          "unit": "kg"
        },
        "by": {
          "kind": "code",
          "value": "volume"
        }
      },
      "message": "快递计费重：较大值（8100 kg，10800 kg）= 10800 kg，按体积"
    }
  ],
  "warnings": [
    {
      "code": "cbm.more_than_20gp",
      "values": {
        "totalVolume": {
          "kind": "quantity",
          "value": "54",
          "unit": "m3"
        },
        "gp20Volume": {
          "kind": "quantity",
          "value": "33.115",
          "unit": "m3"
        }
      },
      "level": "hint",
      "next": "zhuanggui",
      "message": "总体积 54 m3，超过一个 20GP 的容积（约 33.115 m3），看看用什么柜、要几个柜。"
    }
  ],
  "links": {
    "page": "https://chukoudan.com/cbm/?cartons=60x40x50x18x450&lengthUnit=cm&weightUnit=kg&mode=lcl"
  },
  "provenance": {
    "api": "v1",
    "site": "chukoudan.com",
    "generated_at": "2026-10-07T04:00:00.000Z",
    "language": "zh-CN",
    "source_line": "来源：出口单 chukoudan.com · 数据 2026-09-24",
    "notice": "本站非官方渠道，仅供参考，以官方公布为准。",
    "datasets": [
      {
        "id": "divisors",
        "version": "2026-09-24-2",
        "published_at": "2026-09-24",
        "origin": "chukoudan-divisors",
        "source": "体积重系数：常用系数（2026-09-24 整理），以承运商为准"
      },
      {
        "id": "containers",
        "version": "2026-09-24-2",
        "published_at": "2026-09-24",
        "origin": "chukoudan-container-reference",
        "source": "柜型尺寸和最大载重：常用参考值（2026-09-24 整理），以承运商为准"
      }
    ],
    "license": {
      "status": "approved",
      "ours": "dataset.license.ours",
      "underlying": "dataset.license.underlying"
    }
  }
}

The warning is a hint (cbm.more_than_20gp): 54 m³ does not fit one 20GP, and next is the slug of a page that carries on from there.

A dataset

GET /v1/datasets lists the datasets the site shows; /v1/datasets/ID lists a dataset's versions; /v1/datasets/ID/current gives the rows of the current version and /v1/datasets/ID/VERSION a named one, which never changes once published. Each version has a content_hash, so you can tell whether what you hold is the same. Dataset answers link the CSV and JSON downloads.

リクエスト

curl 'https://chukoudan.com/v1/datasets/ports/current?limit=2&lang=en'

レスポンス

HTTP 200
access-control-allow-origin: *
cache-control: public, max-age=60
content-type: application/json
etag: W/"5b2ec780f1e15a548c7a9f6a14a7b02d"
ratelimit-limit: 60
ratelimit-remaining: 59
ratelimit-reset: 1

{
  "dataset": "ports",
  "version": "2026-09-25",
  "published_at": "2026-09-25",
  "fetched_at": "2026-09-24T19:59:07Z",
  "content_hash": "sha256:a222c1be3c0bd7146efc3a2b6a5f9ac0d246edfd4570b6075cfd6b0494eb37af",
  "rows": 38,
  "columns": [
    "id",
    "name.zh-CN",
    "name.en",
    "name.ja",
    "name.ko",
    "region",
    "search.zh",
    "search.pinyin",
    "search.en"
  ],
  "current": true,
  "links": {
    "self": "/v1/datasets/ports/2026-09-25",
    "csv": "/data/ports/2026-09-25.csv",
    "json": "/data/ports/2026-09-25.json"
  },
  "license": {
    "ours": "dataset.license.ours",
    "underlying": "dataset.license.underlying.free",
    "draft": false
  },
  "offset": 0,
  "limit": 2,
  "next": 2,
  "data": [
    {
      "id": "shanghai",
      "name": {
        "zh-CN": "上海",
        "en": "Shanghai",
        "ja": "上海",
        "ko": "상하이"
      },
      "region": "上海",
      "search": {
        "zh": [
          "上海港",
          "洋山"
        ],
        "pinyin": [
          "sh",
          "shg"
        ],
        "en": [
          "Yangshan"
        ]
      }
    },
    {
      "id": "ningbo",
      "name": {
        "zh-CN": "宁波",
        "en": "Ningbo",
        "ja": "寧波",
        "ko": "닝보"
      },
      "region": "浙江",
      "search": {
        "zh": [
          "宁波舟山",
          "北仑",
          "舟山"
        ],
        "pinyin": [
          "nb",
          "nbzs"
        ],
        "en": [
          "Ningbo-Zhoushan",
          "Beilun"
        ]
      }
    }
  ],
  "provenance": {
    "api": "v1",
    "site": "chukoudan.com",
    "generated_at": "2026-10-07T04:00:00.000Z",
    "language": "en",
    "source_line": "Source: 出口单 (Chukoudan), chukoudan.com · data 2026-09-25",
    "notice": "This site is not an official channel. It is for reference only; the official publication prevails.",
    "datasets": [
      {
        "id": "ports",
        "version": "2026-09-25",
        "published_at": "2026-09-25",
        "origin": "chukoudan-port-list",
        "source": null
      }
    ],
    "license": {
      "status": "approved",
      "ours": "dataset.license.ours",
      "underlying": "dataset.license.underlying"
    }
  }
}

A row keeps the stored strings exactly as published. Page with offset and limit; next is null on the last page.

これらの例は、APIのコード自体を2026-10-07に実行して取得したもので、編集していません。

The full description

GET /v1/openapi.json is the machine-readable description (OpenAPI 3.1) of every path, answer and tool input. It is generated from the tools themselves, so it cannot differ from what the API does. The tables of each tool's inputs below come from it.

/v1/openapi.json

OpenAPI 3.0 までしか読めないインポート用ツール（たとえば Coze（扣子））のために、同じ内容の 3.0 版も提供しています。

/v1/openapi-3.0.json

ツールと入力項目

各ツールのアドレスは /v1/tools/ にIDと /compute を付けたものです。以下に、入力項目、返す数値、参照するデータを示します。