荷物追跡APIリファレンス - リアルタイム配送追跡
リアルタイム荷物追跡API。ヤマト運輸、日本郵便、USPS、DHLなど世界中の配送会社を追跡。単件・バッチ追跡、コード例付き。
概要
最大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)
{
"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)
{
"success": false,
"error": {
"code": "REQUEST_VALIDATION_FAILED",
"message": "1 invalid item(s) found"
}
} エラーレスポンス (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} エラーレスポンス (403)
{
"success": false,
"error": {
"code": "DEMO_KEY_BROWSER_ONLY",
"message": "This test key only works from the WhereParcel Playground (https://whereparcel.com/playground)."
}
} エラーレスポンス (429)
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Please try again later."
}
} 概要
入力した追跡番号の形式に一致する配送業者を、最も具体的なものから (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)
{
"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)
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "Field \"trackingNumber\" (string) is required in request body."
}
} エラーレスポンス (401)
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
}