荷物追跡API
無料で始める ダッシュボード

ドキュメント

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

概要

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

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

認証

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

Authorization: Bearer {apiKey}:{secretKey}

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

配送状況の取得

POST/v1/tracking/trace

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

$ 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 }
  }
}

利用状況の確認

現在のプランと今期の利用件数を、コードからそのまま確認できます。上限に達してから気づくことがないよう、この値をご利用ください。

レスポンスに含まれる apiKeyInfo

POST /v1/tracking/trace のレスポンスには apiKeyInfo が一緒に返ります。追加の呼び出しなしで残り件数を確認できます。

{
  "isSuccess": true,
  "data": { ... },
  "apiKeyInfo": {
    "plan": "free",
    "planName": "無料",
    "quota": {
      "limit": 3000,
      "used": 412,
      "remaining": 2588,
      "resetAt": "2026-09-01"
    }
  }
}
フィールド説明
planプランコード
planNameプラン表示名
quota.limit今期に取得できる最大件数
quota.used今期に使用した件数
quota.remaining残り件数。0 の場合は上限に達しています
quota.resetAt利用件数がリセットされる日付。無料プランは翌月1日です

上限は件数で数えます。1回の POST /v1/tracking/trace に追跡番号を複数まとめた場合、呼び出し1回ではなく、含めた件数がそのまま利用件数に反映されます。

利用状況の取得

GET/v1/usage

同じ内容を単独で取得します。この呼び出しは利用件数に含まれません。

$ curl -H "Authorization: Bearer __API_KEY__:__SECRET_KEY__" \
  https://api.trackingapi.jp/v1/usage

配送会社コード

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

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

ステータスコード

deliveryStatus は配送会社ごとの表記を統一したコードです。UNKNOWN は未対応の表記が来た場合のフォールバックです。

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

エラーコード

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

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