Shipping & Tracking Data Normalization

Unify shipping and tracking data from UPS, FedEx, USPS, DHL, and any carrier into one canonical shipment schema. Send tracking numbers and optional carrier payloads; get normalized status, event timeline, provenance, and confidence. Stateless, 25MB max

原始信息汇总

数据集详情总结

数据集基本信息

• 数据集名称：Shipping & Tracking Data Normalization
• 数据集类别：Logistics / Shipping & Tracking
• API版本：v1 (current)
• 主要端点：POST /normalize

数据集概述

该API用于将来自UPS、FedEx、USPS、DHL等不同物流承运商的跟踪数据，规范化为统一的标准化运输模式。通过单次API调用，即可处理单个或多个混合的跟踪号码（可选择是否包含预获取的承运商数据），返回统一的运输状态、按时间顺序排列的事件时间线、位置信息、交付元数据、数据来源和置信度。

核心功能

• 数据规范化：将承运商特定的跟踪数据（或仅跟踪号码）转换为一致的JSON结构，包括标识符、承运商、当前状态、事件时间线、交付信息、来源和置信度。
• 单一模式：无论承运商如何，每个运输数据都具有相同的结构；状态映射到固定的分类标准。
• 混合承运商支持：单个请求中可处理多个输入（跟踪号码、可选的承运商、可选的原始数据）；返回结果、运输数据和项目范围的错误，单个错误项目不会导致整个请求失败。
• 承运商检测：当未声明承运商时，API会根据跟踪号码模式推断承运商；声明与检测不匹配会产生警告并降低置信度。
• 来源与置信度：每个运输数据都包含数据源类型、解析策略和0-1的置信度评分。
• 无承运商API密钥：用户发送跟踪号码和（可选的）已有数据；API不会从承运商处获取数据。无状态，最大请求大小为25MB。

关键特性

• 无状态：不存储或记录数据；最大请求为25MB。
• 支持的承运商：UPS、FedEx、USPS、DHL为首选规范化对象；其他承运商或用户提供的数据可使用custom/unknown。
• 标准状态分类：包括pending、label_created、accepted、in_transit、out_for_delivery、delivered、exception、failed_attempt、returned、cancelled、customs_cleared、unknown。
• 事件时间线：按时间顺序排列的事件，包含标准状态、原始承运商状态、ISO时间戳、位置、事件类型。
• 交付元数据：包括预计交付日期、实际交付时间戳、签收人、交付证明（如果存在，从不伪造）。
• 部分成功：支持逐项结果和错误；元数据包含规范化计数和错误计数。

适用场景

• 市场订单跟踪：将来自多个卖家和承运商的跟踪数据规范化为客户仪表板的统一视图。
• 客户支持：为客服人员提供统一的时间线和状态，而非承运商特定的术语。
• 分析与商业智能：摄取规范化事件以分析不同承运商的交付性能。
• 通知系统：当标准状态变化时触发警报。
• 履行与订单管理系统：为所有入站跟踪数据提供统一模式。

端点详情

• 方法：POST
• 路径：/normalize
• 描述：规范化一个或多个跟踪输入。

输入要求

请求体必须包含一个inputs数组，每个元素包含：

• trackingNumber（必需）：跟踪号码。
• carrier（可选）：例如ups、fedex、usps、dhl、custom。如果省略，则根据跟踪号码模式推断承运商；声明与检测不匹配会产生警告。
• payload（可选）：预获取的承运商JSON数据以供规范化。如果省略，API将返回最小化的运输数据（承运商，无事件）并发出警告。

输出结构

• results：每个输入的结果，包括索引、跟踪号码、运输数据（或null）、可选的错误、可选的警告。
• shipments：所有成功规范化的运输数据（标准模式）。
• errors：项目范围的错误，包括代码、消息、跟踪号码、索引、详细信息。
• metadata：包括totalInputItems、normalizedCount、errorCount。

支持的承运商

• ups：UPS
• fedex：FedEx
• usps：USPS
• dhl：DHL Express
• custom / unknown：自定义/其他承运商，尝试从通用字段（事件、状态）进行规范化。

其他承运商名称（如canada_post、royal_mail）将回退到自定义规范化。

标准运输模式摘要

每个规范化的运输数据在shipments中具有相同的结构：

• identifiers：跟踪号码、承运商跟踪号码、参考号码、先前跟踪号码（如果存在）。
• carrier：承运商ID。
• currentStatus：标准状态之一。
• originalCarrierStatus：承运商的原始状态字符串。
• events：按时间顺序排列的跟踪事件数组。
• delivery：可用时包含预计交付日期、实际交付时间戳、签收人、交付证明等。
• provenance：承运商、数据源类型、解析策略。
• confidence：置信度评分和警告数组。

设计说明与限制

• 无状态：不存储数据；所有处理均在内存中进行。
• 仅输入：API不会获取或查询承运商API；用户提供已有的跟踪号码和（可选的）数据。
• 部分成功：返回逐项错误；其他输入仍被规范化。
• 不虚构数据：缺失的预计交付日期、位置或时间戳保持为null；状态仅根据观察到的数据设置。
• 最大负载大小：每个请求25MB。
• 无承运商API密钥：不向承运商发出出站调用。
• 过大的请求：返回HTTP 413错误。