API Reference

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

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

プレイグラウンドで試すクイックスタートガイド → 7日間無料トライアルを開始 →

EndpointPOST/v2/track

配送追跡 (課金対象)

概要

最大5件まで一度に追跡可能。1件あたり平均応答時間5秒。ヤマト運輸、佐川急便、日本郵便、DHLなど500社以上の配送業者に対応。

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

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

us.ups, us.usps, us.fedex, us.dhl, us.dhl.express, us.dhl.ecommerce, intl.ups, intl.usps, intl.fedex, intl.dhl, gb.royalmail, gb.royalmail.special, gb.evri, gb.ups, ca.ups, ca.fedex, de.ups, es.ups, ie.ups, au.post

このリストは変更される場合があります。上限を超えると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、X-RateLimit-Remaining、X-RateLimit-Resetで現在の使用量を確認できます。

プラン	分あたり	月あたり
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_d5waw8abfqor', 'sk_test_public_demo_mj7ya1taqmaqfkv6lpwe');

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_d5waw8abfqor:sk_test_public_demo_mj7ya1taqmaqfkv6lpwe" \
  -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_d5waw8abfqor:sk_test_public_demo_mj7ya1taqmaqfkv6lpwe",
    "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_d5waw8abfqor:sk_test_public_demo_mj7ya1taqmaqfkv6lpwe',
  '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_d5waw8abfqor:sk_test_public_demo_mj7ya1taqmaqfkv6lpwe',
    '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_d5waw8abfqor:sk_test_public_demo_mj7ya1taqmaqfkv6lpwe")
	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))
}

TIP: テスト用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",
      "status": "success",
      "billable": true,
      "cached": false,
      "data": {
        "deliveryStatus": "delivered",
        "events": [
          {
            "timestamp": "2026-02-05T14:30:00+09:00",
            "status": "delivered",
            "location": "서울 강남구",
            "description": "고객님께 배달이 완료되었습니다"
          },
          {
            "timestamp": "2026-02-05T09:15:00+09:00",
            "status": "out_for_delivery",
            "location": "서울 강남구 센터",
            "description": "배달 출발"
          },
          {
            "timestamp": "2026-02-04T18:00:00+09:00",
            "status": "in_transit",
            "location": "서울 송파구 센터",
            "description": "집하"
          }
        ],
        "from": {
          "name": "홍**"
        },
        "to": {
          "name": "김**"
        },
        "lastUpdated": "2026-02-05T14:30:00+09:00"
      }
    },
    {
      "carrier": "kr.hanjin",
      "trackingNumber": "987654321098",
      "status": "success",
      "billable": true,
      "cached": false,
      "data": {
        "deliveryStatus": "in_transit",
        "events": [
          {
            "timestamp": "2026-02-05T12:00:00+09:00",
            "status": "in_transit",
            "location": "경기 성남시",
            "description": "간선상차"
          }
        ],
        "lastUpdated": "2026-02-05T12:00:00+09:00"
      }
    }
  ]
}

エラーレスポンス (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."
  }
}