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회분만 있는 요청자가 두 번째 요청에서 받는 응답:

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를 붙인 것입니다. 아래에 입력 항목, 반환하는 값, 읽는 데이터를 나열합니다.