Global Parcel Tracking a.k.a GPT

Universal tracking API for 1400+ carriers in 94 countries. Real-time webhook notifications, checkpoint history, and unified status updates. One integration, global coverage.

原始信息汇总

Global Parcel Tracking a.k.a GPT 数据集概述

基本信息

• 名称: Global Parcel Tracking a.k.a GPT
• 类别: Logistics
• 提供者: 0x_wzhenkai
• 订阅者: 4
• 流行度: 9.3
• 服务等级: 100%
• 延迟: 234ms
• 测试通过率: 100%

定价计划

计划	月费	包含请求数	单次请求成本	超额费率
BASIC	$0.00 / mo	未明确	未明确	未明确
PRO	$18.00 / mo	150	$0.12	$0.14
ULTRA	$37.00 / mo	350	$0.10	$0.12
MEGA	$64.00 / mo	700	$0.09	$0.10

核心特性

• 覆盖范围: 支持 94个国家 的 1400+ 家承运商。
• 统一数据格式: 无论承运商是谁，响应结构保持一致。
• 实时Webhook通知: 当货物状态变更时推送通知，无需轮询。
• 检查点历史: 包含时间戳和位置的完整追踪时间线。
• 99% 正常运行时间SLA: 专为高可靠性设计。

支持的承运商亮点

• 目录: 提供1400多家承运商的完整参考目录，按9个全球区域排序。
• 代表性承运商: FedEx, UPS, DHL, USPS, China Post, Japan Post, Royal Mail等。

可用端点

方法	端点	描述
GET	/get_couriers	获取所有1400+家支持的承运商列表
GET	/get_couriers_group_by_country	按国家/地区组织的承运商列表
GET	/get_trackings	检索您正在追踪的货物
POST	/create_tracking	开始追踪一个新的包裹
POST	/cancel_tracking	停止追踪一个货物
POST	/register_webhook	设置实时推送通知

Webhook 通知系统

• 核心功能: 注册一次端点，即可自动接收推送更新。
• 更新频率: 单个货物在其运输过程中会产生多个Webhook通知（每次状态变更或检查点更新）。
  • 典型流程: Pending → InfoReceived → InTransit (多个检查点) → OutForDelivery → Delivered
  • 国内货物: 约3-8次更新
  • 国际货物: 约10-20+次更新
• 可靠投递: 类似Stripe的行为。
  • 如果端点暂时不可用，系统会以指数退避方式重试。
  • 重试持续3天 (1min → 5min → 30min → 2hr → 8hr → 24hr → 48hr)。
  • 每个事件最多尝试投递8次。
• Payload包含:
  • 当前状态和子状态
  • 完整的检查点历史
  • 预计送达日期（如有）
  • 始发地和目的地详情

状态标签参考

标签	描述	Webhook 频率
Pending	追踪已创建，等待首次扫描	1次通知
InfoReceived	承运商已收到货物信息	1次通知
InTransit	货物正在网络中运输	多次（每次扫描）
OutForDelivery	正在派送中	1次通知
AttemptFail	派送尝试失败	每次尝试1次通知
AvailableForPickup	在取件点待取	1次通知
Delivered	已成功送达	1次通知（最终）
Exception	发生问题需关注	1+次通知
Expired	30天以上无更新	1次通知（最终）

架构亮点

• 异步优先设计: 整个技术栈使用Python的asyncio进行非阻塞I/O。
• Redis驱动的队列: 通过ARQ（异步Redis队列）自动排队和重试受速率限制的请求。
• PostgreSQL与异步驱动: 通过连接池实现高性能数据库操作。
• 自动重试逻辑: 对失败的承运商API调用和Webhook投递采用指数退避重试。
• 水平可扩展性: 无状态API服务器位于负载均衡器之后，后台作业有独立的工作进程。

适用场景

• 电子商务平台 – 自动通知客户
• 订单管理系统 – 集中货物可视性
• 物流仪表板 – 监控整体派送表现
• 客户服务工具 – 即时回答“我的包裹在哪里？”
• 运输分析 – 追踪承运商表现和派送时间
• 代发货业务 – 大规模监控供应商货物
• 第三方物流提供商 – 为客户提供追踪可视性

错误响应格式

所有端点均返回以下格式的错误： json { "detail": "描述错误原因的信息" }

主要错误代码

代码	描述
400	错误请求 - 参数无效
401	未授权 - API凭证无效
404	未找到 - 追踪不存在
409	冲突 - 资源已存在
422	验证错误 - 检查请求体
429	速率限制 - 请求已自动排队
500	服务器错误 - 请重试

搜集汇总

背景与挑战

背景概述

该数据集是一个全球包裹追踪API，支持1400多家承运商和94个国家的覆盖，提供实时通知、历史记录和统一状态更新。通过单一集成即可实现全球范围的追踪服务。