API

无需密钥，无需账号

不用注册，直接请求即可。接口不设 Cookie，也不保存你发给计算的输入。限制是按请求方设置的，而不是用密钥。

请求限制

每个请求方可连续发出最多 60 次请求，之后按每分钟 60 次补充。请求方按 IP 地址区分（IPv6 按其 /64 网段）。每个响应的头里都写明你的余量：RateLimit-Limit 是满桶的大小，RateLimit-Remaining 是剩余次数，RateLimit-Reset 是桶重新装满还要多少秒。用完后返回 429，并带 Retry-After 头：再次请求前需要等待的秒数。

一页数据行按每 1000 行算一次请求。一次最多取 5000 行（limit），offset 用来跳过行。计算请求的正文最多 256 KB，且必须是 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": {}
    }
  ],
  "provenance": {
    "api": "v1",
    "site": "chukoudan.com",
    "generated_at": "2026-10-07T04:00:00.000Z",
    "language": "zh-CN",
    "datasets": [],
    "license": {
      "status": "draft",
      "ours": "dataset.license.ours",
      "underlying": "dataset.license.underlying"
    }
  }
}

缓存

可以保存的响应带有 ETag 和 Cache-Control：数据集列表、数据集的版本列表和当前版本的数据行可保存 1 分钟，工具说明 5 分钟，不是当前版本的数据行 1 天。请求时带上 If-None-Match，内容没有变化就得到 304 和空正文，304 仍计入请求限制。出错的响应和所有计算结果都不保存（no-store）。

从浏览器调用

任何网站都可以在访客的浏览器里调用这些接口（GET 和 POST，不带凭据）。计算只接受 JSON：其他内容类型会被拒绝，返回 415。

响应的样子

一次计算返回 tool（工具编号）、outputs（按名称列出的各个数字）、steps（逐行的计算过程）、warnings 和 provenance。输入不合格时返回 400 和 issues，而不是 outputs。响应里没有句子：steps、warnings 和 issues 只带文案键（如 cbm.more_than_20gp）和用来填入的数值，文字由你用自己的语言来写。

数字的写法

每个数字都带类型标记，告诉你该怎么写，数值一律是精确的十进制字符串，绝不是浮点数。quantity 有 value、unit，有时还有 places（保留的小数位数：补零到这个位数，不要再四舍五入）；money 有 amount 和 currency；ratio 是小数形式的比例（0.13 即 13%）；rate 表示 per 个 base 兑 value 个 quote；另有 count、code（来自固定清单的标记）和 date。

数字从哪里来

每个响应（包括错误）都带 provenance：api（版本，v1）、site、generated_at、language，以及 datasets（这次回答用到的每个数据集版本，含 published_at 日期、origin 和可以引用的来源说明）和 license。在任何请求上加 lang=zh-CN、en、ja 或 ko，可选择来源说明的语言，其他内容不变。license 目前是草案，在文本获得批准之前，里面是文案键而不是文字。

错误

错误响应有 issues（每项含 path、code、values）和 provenance。400：输入被拒绝（path 指出是哪个字段，code 说明原因，code 是文案键）；404：没有这个工具、数据集或版本；413：正文过大；415：不是 JSON；429：超过限制；500：我们这边出了问题，响应不会说明更多原因。

一次计算

把工具的输入 POST 到 /v1/tools/ID/compute。下面的例子算的是：450 箱，每箱 60 × 40 × 50 cm、18 kg，走拼箱（LCL）的立方米数。在 CBM 页面输入同样的数据，得到的是同样的数字。

请求

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"
        },
        "grossWeight": {
          "kind": "quantity",
          "value": "18",
          "unit": "kg"
        },
        "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"
        },
        "weight": {
          "kind": "quantity",
          "value": "8100",
          "unit": "kg"
        },
        "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
        }
      }
    },
    {
      "id": "cbm.total",
      "values": {
        "totalVolume": {
          "kind": "quantity",
          "value": "54",
          "unit": "m3"
        },
        "totalGrossWeight": {
          "kind": "quantity",
          "value": "8100",
          "unit": "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"
        }
      }
    },
    {
      "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"
        }
      }
    },
    {
      "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"
        }
      }
    }
  ],
  "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"
    }
  ],
  "provenance": {
    "api": "v1",
    "site": "chukoudan.com",
    "generated_at": "2026-10-07T04:00:00.000Z",
    "language": "zh-CN",
    "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": "draft",
      "ours": "dataset.license.ours",
      "underlying": "dataset.license.underlying"
    }
  }
}

warnings 里有一条 hint（cbm.more_than_20gp）：54 m³ 装不进一个 20GP，next 是可以接着用的工具的页面标识。

一个数据集

GET /v1/datasets 列出网站展示的数据集；/v1/datasets/ID 列出某个数据集的各个版本；/v1/datasets/ID/current 返回当前版本的数据行；/v1/datasets/ID/VERSION 返回指定版本，已发布的版本永不改变。每个版本有 content_hash，可以用来判断你手上的是不是同一份。数据集的响应里都带有 CSV 和 JSON 下载的链接。

请求

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/"5e81138d2bd087290f4dbc776003b1cf"
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": true
  },
  "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",
    "datasets": [
      {
        "id": "ports",
        "version": "2026-09-25",
        "published_at": "2026-09-25",
        "origin": "chukoudan-port-list",
        "source": null
      }
    ],
    "license": {
      "status": "draft",
      "ours": "dataset.license.ours",
      "underlying": "dataset.license.underlying"
    }
  }
}

数据行里的数字保持发布时的字符串原样。翻页用 offset 和 limit；最后一页的 next 是 null。

示例是用本站接口自己的代码在 2026-10-07 实际运行得到的，没有改动。

完整说明

GET /v1/openapi.json 是机器可读的说明（OpenAPI 3.1），涵盖每个路径、响应和每个工具的输入；它由工具本身生成，所以不会与接口的实际行为不一致。下面各工具的输入表就来自它。

/v1/openapi.json

计算器及其输入项

每个计算器的地址是 /v1/tools/ 加它的编号，再加 /compute。下面列出每个计算器的输入项、返回的数值和读取的数据。