荷物追跡APIリファレンス - リアルタイム配送追跡 | WhereParcel
無料プラン提供のリアルタイム荷物追跡API。ヤマト運輸、佐川急便、日本郵便など世界中の配送会社を追跡。単件・バッチ追跡、コード例付き。
POST
/v2/track 配送追跡 (課金対象)
概要
最大5件まで一度に追跡可能。1件あたり平均応答時間5秒。ヤマト運輸、佐川急便、日本郵便、DHLなど500社以上の配送業者に対応。
このエンドポイントの用途:
/v2/trackは単発の照会に使用してください。例:ECサイトで顧客が注文状況を確認する場合。
継続的なモニタリングにはWebhookを使用してください。
DB更新や通知送信など、配送状況を継続的に追跡する必要がある場合は、/v2/webhooks/registerでrecurring: trueのサブスクリプションを登録してください。ポーリングの代わりに、ステータスが変更された時のみプッシュ通知を受信するため、はるかに効率的です。
リクエスト制限:
プランごとに分あたり・月あたりのリクエスト制限が適用されます。制限超過時はHTTP 429を返します。レスポンスヘッダーX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetで現在の使用量を確認できます。
| プラン | 分あたり | 月あたり |
|---|---|---|
| Free | 1 | 5 |
| Starter | 30 | 10,000 |
| Pro | 60 | 30,000 |
| Business | 200 | 300,000 |
リクエスト例
// npm install whereparcel
import { WhereParcel } from 'whereparcel';
const wp = new WhereParcel('wp_test_public_demo_key_do_not_use_in_production', 'sk_test_public_demo_secret_do_not_use_in_production');
const response = await wp.trackBulk([
{
"carrier": "kr.cj",
"trackingNumber": "123456789012"
},
{
"carrier": "de.gls",
"trackingNumber": "48117308687"
}
]);
console.log(response.summary);
for (const result of response.results) {
if (result.status === 'success') {
console.log(result.data.deliveryStatus);
}
}curl -X POST https://api.whereparcel.com/v2/track \
-H "Authorization: Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production" \
-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 wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production",
"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 wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production',
'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$data = [
'trackingItems' => [
'0' => [
'carrier' => "kr.cj",
'trackingNumber' => "123456789012"
],
'1' => [
'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
import json
url = 'https://api.whereparcel.com/v2/track'
headers = {
'Authorization': 'Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production',
'Content-Type': 'application/json'
}
data = {
'trackingItems': {
'0': {
'carrier': "kr.cj",
'trackingNumber': "123456789012"
},
'1': {
'carrier': "de.gls",
'trackingNumber': "48117308687",
'postalCode': "04179"
}
}
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)package main
import (
"bytes"
"encoding/json"
"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 wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production")
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キーに置き換えてください。
リクエストボディ
| Name | Type | Required | Description |
|---|---|---|---|
trackingItems | array | Required | |
trackingItems[].carrier | string | Required | 配送業者コード(例: 'kr.cj', 'us.fedex', 'de.gls') |
trackingItems[].trackingNumber | string | Required | 追跡番号 |
trackingItems[].clientId | string | Optional | クライアント追跡ID(レスポンスにそのまま返却) |
trackingItems[].postalCode | string | Optional | 郵便番号(一部の配送業者で必須/任意、例: GLS Germany) |
trackingItems[].phoneNumber | string | Optional | 電話番号(一部の配送業者で必須/任意) |
レスポンス
成功レスポンス (200)
200 OK
追跡応答成功
Response Body
{
"success": true,
"results": [
{
"carrier": "kr.cj",
"trackingNumber": "123456789012",
"clientId": "order-123",
"success": true,
"data": {
"carrier": "kr.cj",
"carrierName": "CJ대한통운",
"trackingNumber": "123456789012",
"status": "delivered",
"statusText": "배달완료",
"events": [
{
"timestamp": "2026-02-05T14:30:00+09:00",
"status": "delivered",
"statusText": "배달완료",
"location": "서울 강남구",
"description": "고객님께 배달이 완료되었습니다"
},
{
"timestamp": "2026-02-05T09:15:00+09:00",
"status": "out_for_delivery",
"statusText": "배달 출발",
"location": "서울 강남구 센터"
},
{
"timestamp": "2026-02-04T18:00:00+09:00",
"status": "in_transit",
"statusText": "집하",
"location": "서울 송파구 센터"
}
]
}
},
{
"carrier": "kr.hanjin",
"trackingNumber": "987654321098",
"success": true,
"data": {
"carrier": "kr.hanjin",
"carrierName": "한진택배",
"trackingNumber": "987654321098",
"status": "in_transit",
"statusText": "배송 중",
"events": [
{
"timestamp": "2026-02-05T12:00:00+09:00",
"status": "in_transit",
"statusText": "간선상차",
"location": "경기 성남시"
}
]
}
}
]
} エラーレスポンス (401)
401 Unauthorized
認証失敗 - APIキーがないか無効です
Response Body
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} エラーレスポンス (429)
429 Too Many Requests
リクエスト制限超過
Response Body
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Please try again later."
}
}