荷物追跡API
無料で始める

ドキュメント

追跡番号を送るだけで、ヤマト運輸・佐川急便・日本郵便の配送状況を統一フォーマットで取得できます。ここではリクエストの方法とレスポンスの形式を説明します。

概要

荷物追跡APIは REST API です。すべてのリクエストは https://api.trackingapi.jp に対して HTTPS で送信し、レスポンスは JSON で返ります。

同じ追跡番号を短時間に繰り返し取得するより、Webhook購読で状況変化を受け取る方が効率的です。

認証

すべてのリクエストに Authorization ヘッダーを付与します。API キーとシークレットキーをコロンで連結し、Bearer トークンとして送信します。

Authorization: Bearer {apiKey}:{secretKey}

キーはダッシュボードから発行できます。登録は無料です。

配送状況の取得

POST/v1/tracking/trace

items に配送会社コードと追跡番号の組を指定します（1回のリクエストで最大100件）。

$ curl https://api.trackingapi.jp/v1/tracking/trace \
  -H "Authorization: Bearer pk_***:sk_***" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "courierCode": "yamato", "trackingNumber": "490381075682" }
    ]
  }'
const res = await fetch("https://api.trackingapi.jp/v1/tracking/trace", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pk_***:sk_***",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    items: [{ courierCode: "yamato", trackingNumber: "490381075682" }]
  })
});
const data = await res.json();
import requests

res = requests.post(
    "https://api.trackingapi.jp/v1/tracking/trace",
    headers={"Authorization": "Bearer pk_***:sk_***"},
    json={"items": [{"courierCode": "yamato", "trackingNumber": "490381075682"}]},
)
data = res.json()

レスポンス

data.results に各追跡番号の結果が入ります。配送状況は deliveryStatus（コード）と deliveryStatusText（日本語）の両方で返ります。

{
  "isSuccess": true,
  "data": {
    "results": [{
      "success": true,
      "data": {
        "courierName": "ヤマト運輸",
        "deliveryStatus": "DELIVERED",
        "deliveryStatusText": "配達完了",
        "isDelivered": true,
        "progresses": [ /* 配送履歴 */ ]
      }
    }],
    "summary": { "total": 1, "successful": 1, "billable": 1 }
  }
}

配送会社コード

courierCode には以下を指定します。「準備中」の会社はリクエストを受け付け、対応後に取得できるようになります（準備中は課金されません）。

courierCode配送会社状態
yamatoヤマト運輸対応中
sagawa佐川急便対応中
post日本郵便対応中
seino西濃運輸準備中
fukutsu福山通運準備中
nittsu日本通運準備中
meitetsu名鉄運輸準備中
tonamiトナミ運輸準備中
daiichi第一貨物準備中
nishitetsu西日本鉄道準備中
kurume久留米運送準備中

ステータスコード

deliveryStatus は配送会社ごとの表記を統一したコードです。

deliveryStatus意味
REGISTERED受付
PICKED_UP集荷完了
IN_TRANSIT輸送中
OUT_FOR_DELIVERY配達中
DELIVERED配達完了
FAILED持ち戻り・不在
RETURNED返送
CANCELLEDキャンセル
HOLD保管中

エラーコード

各 result が失敗した場合、error.code に理由が入ります。

code意味課金
INVALID_TRACKING_NUMBER追跡番号の形式が不正なし
UNSUPPORTED_COURIER非対応の配送会社コードなし
NOT_FOUND該当する配送情報が見つからないあり
COURIER_PREPARING準備中の配送会社なし
TRACKING_FAILED一時的なエラー。時間をおいて再試行なし