Read-only endpoint contract

Service version 1.0.0; no version segment in the URL. All paths below are relative to https://api.gathlogistics.com.

GET /rates filters

• origin, destination, pol, pod: case-insensitive substring match on the field of that exact name.
• carrier: case-insensitive exact match.
• All supplied filters are ANDed. origin and pol (and destination and pod) are separate fields, not fallback aliases, despite the metadata wording.
• No pagination, sort or date filtering is implemented. Repeated query names use their last value; unknown parameters are echoed in query but ignored by filtering.

Response fields

/rates: success boolean; query object of string parameters; total number of matching rows; rates array of raw stored row objects. Rows are not normalized by this API.

Observed row fields (all observed values were strings; not all fields are guaranteed on every row): 20GP, 40GP, 40HQ, 45HC, cargoType, carrier, country, currency, destination, directOrTs, freeTime, id, importedAt, importedBy, note, origin, pod, pol, price, remark, serviceMode, source, transitDays, validFrom, validTo, validity.

Prices and container amounts can be text or empty; do not coerce blanks to zero. Do not infer valid dates from free-text validity. Import metadata is not part of a stable required schema and should not be republished.

/rates/stats: success boolean, total_rates number, and arrays carriers, top_origins, top_destinations, each containing {name: string, count: number}. Arrays are descending by count; origin/destination arrays are capped at 10. Statistics are unfiltered and use origin/destination, not pol/pod.

/health: status string ok and ISO timestamp string. / and /docs: name, version, description, endpoints, authentication, query_parameters.

Method and legacy warnings

OPTIONS currently returns generic 204 for any path and advertises GET, POST, OPTIONS. This is CORS behavior, not evidence that POST or a path is implemented. No write operation is documented. Former /wp-json/gath/v1/* quote and order paths are not routes of this deployed service.

只读端点契约

服务版本 1.0.0，URL 不含版本段。以下路径相对 https://api.gathlogistics.com。

GET /rates 筛选参数

• origin、destination、pol、pod：对同名字段不区分大小写的包含匹配。
• carrier：不区分大小写的完整匹配。
• 全部条件取 AND。origin/pol 与 destination/pod 是独立字段，并非回退别名；公开元数据中的“同”不能按别名理解。
• 未实现分页、排序、日期筛选；重复参数取最后值，未知参数仅回显于 query，不参与筛选。

响应字段

/rates：success 为布尔，query 为字符串参数对象，total 为命中条数，rates 为原始存储对象数组；当前 API 不对行字段做规范化。

实际观察到的字段（观察值均为字符串，但不是每条记录的必填承诺）：20GP, 40GP, 40HQ, 45HC, cargoType, carrier, country, currency, destination, directOrTs, freeTime, id, importedAt, importedBy, note, origin, pod, pol, price, remark, serviceMode, source, transitDays, validFrom, validTo, validity.

价格/箱型金额可能为文本或空串，空串不要当零；不要从 validity 自由文本推断有效日期。导入元信息不属于稳定必填契约，不应公开转载。

/rates/stats：success 布尔、total_rates 数值，carriers/top_origins/top_destinations 为 {name: string, count: number} 数组，按 count 降序，起运/目的数组各最多 10 项。统计不应用筛选，使用 origin/destination，而非 pol/pod。

/health：status 字符串 ok、timestamp ISO 时间字符串。/ 与 /docs 返回 name/version/description/endpoints/authentication/query_parameters。

方法及旧路径警告

OPTIONS 对任意路径统一返回 204，并广告 GET、POST、OPTIONS。这只是 CORS 行为，不能证明 POST 或该路径已实现。不发布写操作契约。旧 /wp-json/gath/v1/* 报价、订单路径不属于当前部署的服务。