whereparcel

何か聞きたいことがあれば、気軽にどうぞ。WhereParcelを作った開発者が直接メッセージを読んで返信します。

荷物追跡APIリファレンス - リアルタイム配送追跡

リアルタイム荷物追跡API。ヤマト運輸、日本郵便、USPS、DHLなど世界中の配送会社を追跡。単件・バッチ追跡、コード例付き。

プレイグラウンドで試す クイックスタートガイド → 始める →

EndpointPOST/v2/track
配送追跡 (課金対象)

概要

最大5件まで一度に追跡可能。ヤマト運輸、日本郵便、DHLなど39社以上の配送業者に対応。

一部の配送業者は1リクエストにつき1件まで:

以下の配送業者は照会に時間がかかるため、1回の同期リクエストに含められるのはこれらを合わせて最大1件です。2つを混在させた場合も拒否されます。他の配送業者との併用は可能です — このリストから1件 + その他の配送業者4件 = 合計5件。

us.usps, us.fedex, us.ups, intl.dhl

このリストは変更される場合があります。上限を超えるとINVALID_REQUESTで拒否され、エラーメッセージに該当する配送業者コードが示されます。これらの配送業者を複数追跡する場合は/v2/webhooks/register(最大100件、非同期)をご利用ください。

時刻のないイベント: 一部の配送業者は特定のイベントについて日付のみを提供し、スキャン時刻を返しません(USPS の "In Transit to Next Facility"、"Pre-Shipment" など)。その場合 timestamp は ISO 8601 を保つためその日の正午で補完され、そのイベントに timeUnknown: true が付きます。このフィールドがない場合は、配送業者が時刻まで提供した実際の値です。

このエンドポイントの用途: /v2/trackは単発の照会に使用してください。例:ECサイトで顧客が注文状況を確認する場合。

継続的なモニタリングにはWebhookを使用してください。 DB更新や通知送信など、配送状況を継続的に追跡する必要がある場合は、/v2/webhooks/registerでrecurring: trueのサブスクリプションを登録してください。ポーリングの代わりに、ステータスが変更された時のみプッシュ通知を受信するため、はるかに効率的です。

リクエスト制限: プランごとに分あたり・月あたりのリクエスト制限が適用されます。制限超過時はHTTP 429を返します。レスポンスヘッダーX-RateLimit-Limit-Minute、X-RateLimit-Remaining-Minute、X-RateLimit-Reset-Minute(および-Day・-Month)で現在の使用量を確認できます。

プラン 分あたり 月あたり
Starter 30 10,000
Pro 60 30,000
Business 200 300,000

リクエスト例

// npm install whereparcel
import { WhereParcel } from 'whereparcel';

const wp = new WhereParcel('YOUR_API_KEY', 'YOUR_SECRET_KEY');

const { data, summary } = await wp.track([
  {
    "carrier": "kr.cj",
    "trackingNumber": "123456789012"
  },
  {
    "carrier": "de.gls",
    "trackingNumber": "48117308687"
  }
]);

console.log(summary);
for (const result of data) {
  if (result.status === 'success') {
    console.log(result.carrier, result.data.deliveryStatus);
  }
}
curl -X POST https://api.whereparcel.com/v2/track \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingItems": [
      {
        "carrier": "kr.cj",
        "trackingNumber": "123456789012"
      },
      {
        "carrier": "de.gls",
        "trackingNumber": "48117308687",
        "postalCode": "04179"
      }
    ]
  }'
const response = await fetch('https://api.whereparcel.com/v2/track', {
  method: 'POST',
  headers: {
    "Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
      "trackingItems": [
        {
          "carrier": "kr.cj",
          "trackingNumber": "123456789012"
        },
        {
          "carrier": "de.gls",
          "trackingNumber": "48117308687",
          "postalCode": "04179"
        }
      ]
    })
});

const data = await response.json();
console.log(data);
<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/track');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

$headers = [
  'Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
  'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$data = [
  'trackingItems' => [
    [
      'carrier' => "kr.cj",
      'trackingNumber' => "123456789012"
    ],
    [
      'carrier' => "de.gls",
      'trackingNumber' => "48117308687",
      'postalCode' => "04179"
    ]
  ]
];
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
import requests

url = 'https://api.whereparcel.com/v2/track'

headers = {
    'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
    'Content-Type': 'application/json'
}

data = {
    'trackingItems': [
        {
            'carrier': "kr.cj",
            'trackingNumber': "123456789012"
        },
        {
            'carrier': "de.gls",
            'trackingNumber': "48117308687",
            'postalCode': "04179"
        }
    ]
}

response = requests.post(url, headers=headers, json=data)

result = response.json()
print(result)
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.whereparcel.com/v2/track"

	payload := []byte(`{"trackingItems":[{"carrier":"kr.cj","trackingNumber":"123456789012"},{"carrier":"de.gls","trackingNumber":"48117308687","postalCode":"04179"}]}`)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))

	req.Header.Add("Authorization", "Bearer YOUR_API_KEY:YOUR_SECRET_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

テスト用APIキーをダッシュボードで発行した実際のAPIキーに置き換えてください。

リクエストボディ

trackingItems array · required
trackingItems[].carrier string · required 配送業者コード(例: 'kr.cj', 'us.fedex', 'de.gls')
trackingItems[].trackingNumber string · required 追跡番号
trackingItems[].clientId string クライアント追跡ID(レスポンスにそのまま返却)
trackingItems[].postalCode string 郵便番号(一部の配送業者で必須/任意、例: GLS Germany)
trackingItems[].phoneNumber string 電話番号(一部の配送業者で必須/任意)

レスポンス

成功レスポンス (200)

200OK — 追跡応答成功
{
  "success": true,
  "data": [
    {
      "carrier": "us.fedex",
      "trackingNumber": "231300687629630",
      "clientId": "order-123",
      "status": "success",
      "billable": true,
      "cached": false,
      "data": {
        "deliveryStatus": "delivered",
        "events": [
          {
            "timestamp": "2026-02-04T18:00:00-05:00",
            "status": "in_transit",
            "location": "Newark, NJ",
            "description": "At local FedEx facility"
          },
          {
            "timestamp": "2026-02-05T09:15:00-05:00",
            "status": "out_for_delivery",
            "location": "Brooklyn, NY",
            "description": "On FedEx vehicle for delivery"
          },
          {
            "timestamp": "2026-02-05T14:30:00-05:00",
            "status": "delivered",
            "location": "New York, NY",
            "description": "Delivered, left at front door"
          }
        ],
        "from": {
          "name": "J. Smith"
        },
        "to": {
          "name": "M. Johnson"
        },
        "lastUpdated": "2026-02-05T14:30:00-05:00"
      }
    },
    {
      "carrier": "us.usps",
      "trackingNumber": "9400111899223197428490",
      "status": "success",
      "billable": true,
      "cached": false,
      "data": {
        "deliveryStatus": "in_transit",
        "events": [
          {
            "timestamp": "2026-02-05T12:00:00-05:00",
            "status": "in_transit",
            "location": "Chicago, IL",
            "description": "In transit to next facility"
          }
        ],
        "lastUpdated": "2026-02-05T12:00:00-05:00"
      }
    }
  ],
  "summary": {
    "total": 2,
    "success": 2,
    "failed": 0,
    "usageIncremented": 2
  },
  "requestLimit": {
    "second": "1/10"
  },
  "trackingQuota": {
    "minute": "2/30",
    "day": "2/10000",
    "month": "152/10000"
  }
}

エラーレスポンス (400)

400Bad Request — 不正なリクエスト — 検証失敗 (REQUEST_VALIDATION_FAILED、invalidItems 付き)、1件制限の配送業者の超過 (INVALID_REQUEST)、デモキーの項目数超過 (DEMO_KEY_ITEM_LIMIT_EXCEEDED)
{
  "success": false,
  "error": {
    "code": "REQUEST_VALIDATION_FAILED",
    "message": "1 invalid item(s) found"
  }
}

エラーレスポンス (401)

401Unauthorized — 認証失敗 - APIキーがないか無効です
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

エラーレスポンス (403)

403Forbidden — 拒否 — 公開デモキーは WhereParcel プレイグラウンドからのみ動作します (DEMO_KEY_BROWSER_ONLY)。またはトライアル上限に到達 (TRIAL_LIMIT_REACHED)
{
  "success": false,
  "error": {
    "code": "DEMO_KEY_BROWSER_ONLY",
    "message": "This test key only works from the WhereParcel Playground (https://whereparcel.com/playground)."
  }
}

エラーレスポンス (429)

429Too Many Requests — リクエスト制限・利用量の超過 (RATE_LIMIT_EXCEEDED、MINUTE_QUOTA_EXCEEDED、MONTHLY_QUOTA_EXCEEDED、DEMO_KEY_IP_LIMIT_EXCEEDED)
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  }
}
EndpointPOST/v2/detect
追跡番号から配送業者を判定 (無料)

概要

入力した追跡番号の形式に一致する配送業者を、最も具体的なものから (specificityScore) 返します。形式の照合のみで、配送業者への照会も利用量のカウントもありません。

specificityScore が最も高い候補のコードで /v2/track を呼び出してください。confirmed は一致する配送業者がちょうど1社の場合のみ付きます。

リクエスト例

// npm install whereparcel
import { WhereParcel } from 'whereparcel';

const wp = new WhereParcel('YOUR_API_KEY', 'YOUR_SECRET_KEY');

const detected = await wp.detect('1Z999AA10123456784');

if (detected.confirmed) {
  console.log('carrier:', detected.confirmed);
} else if (!detected.noMatch) {
  console.log('candidates:', detected.candidates.map((c) => c.code));
}
curl -X POST https://api.whereparcel.com/v2/detect \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "1Z999AA10123456784"
  }'
const response = await fetch('https://api.whereparcel.com/v2/detect', {
  method: 'POST',
  headers: {
    "Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
      "trackingNumber": "1Z999AA10123456784"
    })
});

const data = await response.json();
console.log(data);
<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/detect');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

$headers = [
  'Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
  'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$data = [
  'trackingNumber' => "1Z999AA10123456784"
];
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
import requests

url = 'https://api.whereparcel.com/v2/detect'

headers = {
    'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
    'Content-Type': 'application/json'
}

data = {
    'trackingNumber': "1Z999AA10123456784"
}

response = requests.post(url, headers=headers, json=data)

result = response.json()
print(result)
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.whereparcel.com/v2/detect"

	payload := []byte(`{"trackingNumber":"1Z999AA10123456784"}`)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))

	req.Header.Add("Authorization", "Bearer YOUR_API_KEY:YOUR_SECRET_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

テスト用APIキーをダッシュボードで発行した実際のAPIキーに置き換えてください。

リクエストボディ

trackingNumber string · required 確認する追跡番号 (最大100文字、空白・ハイフン・ドットは無視)

レスポンス

成功レスポンス (200)

200OK — 配送業者の候補
{
  "success": true,
  "data": {
    "input": "1Z999AA10123456784",
    "normalized": "1Z999AA10123456784",
    "candidates": [
      {
        "code": "us.ups",
        "name": "UPS (United Parcel Service)",
        "country": "US",
        "pattern": {
          "regex": "^(1Z[A-Z0-9]{16}|T[0-9]{10}|[0-9]{9,34})$",
          "description": "1Z + 16 alphanumeric characters (incl. check digit), T + 10 digits, or 9-34 digits (Mail Innovations/SurePost)",
          "examples": [
            "1ZW4420K0310663099",
            "9216490395160105988026"
          ]
        },
        "specificityScore": 67,
        "formatName": "UPS",
        "serviceTypes": [
          "UPS United States Next Day Air (Red)"
        ]
      },
      {
        "code": "intl.dhl",
        "name": "DHL Express",
        "country": "INTL",
        "pattern": {
          "regex": "^([0-9]{10,39}|[A-Z]{2}[0-9]{9}[A-Z]{2}|JD[0-9]{18,22})$",
          "description": "10-39 digits, international postal format (2 letters + 9 digits + 2 letters), or JD + digits",
          "examples": [
            "1234567890",
            "AB123456789CD"
          ]
        },
        "specificityScore": 20,
        "formatName": "DHL Express",
        "serviceTypes": []
      },
      {
        "code": "ca.loomis",
        "name": "Loomis Express",
        "country": "CA",
        "pattern": {
          "regex": "^[A-Z0-9]{10,30}$",
          "description": "Alphanumeric 10-30 characters (e.g., LSHP46411066, LQJ0Z3N0AALSHP46411066)",
          "examples": [
            "LSHP46411066",
            "LQJ0Z3N0AALSHP46411066"
          ]
        },
        "specificityScore": 2
      },
      {
        "code": "ca.ics",
        "name": "ICS Courier",
        "country": "CA",
        "pattern": {
          "regex": "^[A-Z0-9]{15,25}$",
          "description": "Alphanumeric 15-25 characters (e.g., ND6C2BV3HBB0BEJ9Z1E2)",
          "examples": [
            "ND6C2BV3HBB0BEJ9Z1E2"
          ]
        },
        "specificityScore": 2
      },
      {
        "code": "intl.cainiao",
        "name": "Cainiao",
        "country": "INTL",
        "pattern": {
          "regex": "^(LP[A-Z0-9]{14,20}|[A-Z]{2}[0-9]{9}[A-Z]{2}|CAINIAO[A-Z0-9]+|[A-Z0-9]{10,30})$",
          "description": "LP + 14-20 characters, international postal format, CAINIAO prefix, or 10-30 alphanumeric characters",
          "examples": [
            "LP00123456789012345",
            "AB123456789CD"
          ]
        },
        "specificityScore": 2
      }
    ],
    "format": "1Z + 16 alphanumeric characters (incl. check digit), T + 10 digits, or 9-34 digits (Mail Innovations/SurePost)",
    "noMatch": false
  }
}

エラーレスポンス (400)

400Bad Request — trackingNumber がない、空、または100文字を超えている (INVALID_REQUEST)
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Field \"trackingNumber\" (string) is required in request body."
  }
}

エラーレスポンス (401)

401Unauthorized — 認証失敗 - APIキーがないか無効です
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}