whereparcel

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

チュートリアル 7 分で読めます

追跡データを活用したリアルタイム配達予定日の構築方法

荷物追跡イベントを活用して、正確な配達予定日を計算・表示する方法を解説します。顧客満足度の向上につながるアプリケーション実装のポイントをご紹介します。

WhereParcel Team

お客様から最も多く寄せられる質問の一つが「荷物はいつ届きますか?」です。配送業者が提供する配達予定日は、曖昧だったり不正確だったりすることが少なくありません。リアルタイムの追跡イベントを分析することで、よりスマートで正確な配達予測を構築し、お客様への情報提供を充実させ、問い合わせの削減につなげることができます。

標準的なETAでは不十分な理由

ほとんどの配送業者が提供するETAは出荷時に設定されたまま更新されることがなく、以下のような要因が考慮されていません。

  • 国際配送における通関の遅延
  • 天候による輸送の混乱
  • 配送業者の仕分け施設の滞留
  • ラストマイル配送の課題

リアルタイムの追跡イベントを処理することで、荷物が配送ネットワークを移動するにつれて予測を動的に調整できます。

追跡イベントの収集設定

まず、WhereParcelのWebhookを使用して追跡更新を受信する設定を行います。登録した荷物はポーリングのサイクルごと(数時間おき)に再照会されます。お客様が追跡ページを開いたときは POST /v2/track を呼び出せば最新のデータを取得できます。

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

// 1. Create a webhook endpoint once (free). Keep endpointId, and store the
//    returned secret to verify X-WhereParcel-Signature on incoming webhooks.
const endpoint = await fetch('https://api.whereparcel.com/v2/webhook-endpoints', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Delivery estimates',
    url: 'https://your-app.com/webhooks/tracking',
    description: '配送ステータス更新',
  }),
}).then((r) => r.json());

// 2. Subscribe each shipment (billed once per parcel, up to 100 per call).
//    recurring: true keeps re-checking it until it is delivered.
await fetch('https://api.whereparcel.com/v2/webhooks/register', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    webhookEndpointId: endpoint.data.endpointId,
    recurring: true,
    trackingItems: [{ carrier: 'jp.yamato', trackingNumber: '123456789012' }],
  }),
});

イベントを活用したETA計算

各追跡イベントにはステータス情報とタイムスタンプが含まれており、これらを使って配達予測を構築できます。配送業者が独自の配達予定日を公開している場合、WhereParcelはそれを estimatedDelivery としてそのまま返します。すべての配送業者が提供するわけではないため、答えそのものではなく判断材料の一つとして扱いましょう。

// trackingData = item.trackingData from a webhook, or data[0].data from POST /v2/track
function calculateEstimatedDelivery(trackingData, carrier, destination) {
  const { events, estimatedDelivery } = trackingData;
  const latestEvent = events[events.length - 1];   // events are oldest first

  // Base estimates by standardized status
  // (there is no picked_up or customs status: the first scan after
  //  the label is created already reports in_transit)
  const estimateMap = {
    'pending': { minDays: 2, maxDays: 6 },          // label created, not scanned yet
    'in_transit': { minDays: 1, maxDays: 3 },
    'out_for_delivery': { minDays: 0, maxDays: 0 },
  };

  const estimate = estimateMap[latestEvent.status] || { minDays: 2, maxDays: 7 };

  const now = new Date();
  return {
    earliest: addBusinessDays(now, estimate.minDays),
    latest: addBusinessDays(now, estimate.maxDays),
    confidence: calculateConfidence(events),
    // The carrier's own date, when it publishes one (optional field)
    carrierDate: estimatedDelivery ? new Date(estimatedDelivery) : null,
  };
}

適応型予測モデルの構築

より正確な予測を行うためには、配送業者とルートごとの過去の配達実績を蓄積します。

// Store delivery times for completed shipments
async function recordDeliveryTime(shipment) {
  // First scan after the label was created (there is no picked_up status)
  const pickupDate = shipment.events.find(e => e.status !== 'pending')?.timestamp;
  const deliveryDate = shipment.events.find(e => e.status === 'delivered')?.timestamp;

  if (pickupDate && deliveryDate) {
    await db.deliveryTimes.insert({
      carrier: shipment.carrier,
      originCountry: shipment.origin.country,
      destinationCountry: shipment.destination.country,
      transitDays: daysBetween(pickupDate, deliveryDate),
      recordedAt: new Date(),
    });
  }
}

// Calculate average delivery time for a route
async function getHistoricalAverage(carrier, origin, destination) {
  const records = await db.deliveryTimes
    .find({ carrier, originCountry: origin, destinationCountry: destination })
    .sort({ recordedAt: -1 })
    .limit(100);

  if (records.length < 10) return null; // Not enough data

  const times = records.map(r => r.transitDays);
  return {
    average: Math.round(times.reduce((a, b) => a + b) / times.length),
    p90: percentile(times, 90),
    sampleSize: records.length,
  };
}

UIでの予測表示

配達予測を信頼度レベルとともに分かりやすく表示します。

function DeliveryEstimate({ estimate }) {
  const { earliest, latest, confidence } = estimate;

  if (confidence === 'high') {
    return (
      <div className="estimate high-confidence">
        <span>Expected delivery: {formatDate(earliest)}</span>
      </div>
    );
  }

  return (
    <div className="estimate">
      <span>
        Estimated delivery: {formatDate(earliest)} – {formatDate(latest)}
      </span>
      {confidence === 'low' && (
        <small>Estimate may change based on customs processing</small>
      )}
    </div>
  );
}

エッジケースへの対応

通関を伴う国際配送

通関処理は配達予測における最大の変動要因です。荷物が通関に入った場合は、予測の範囲を広げます。

// No customs status exists: customs scans arrive as in_transit
// with the carrier's wording in description
if (latestEvent.status === 'in_transit' && /customs|clearance/i.test(latestEvent.description)) {
  // Customs can take 1-14 days depending on country
  estimate.latest = addBusinessDays(now, getCustomsEstimate(destination.country));
  estimate.confidence = 'low';
}

配達例外

追跡情報で配達失敗や例外が表示された場合は、それに応じて予測を更新します。

// A missed attempt the carrier will retry usually stays in_transit (USPS: "Notice Left")
if (/notice left|attempted|redelivery/i.test(latestEvent.description)) {
  estimate.earliest = addBusinessDays(now, 1); // Next business day retry
  estimate.latest = addBusinessDays(now, 3);
  estimate.note = 'Delivery was attempted. The carrier will retry.';
}

// failed, returned and lost mean it will not arrive without action
if (['failed', 'returned', 'lost'].includes(latestEvent.status)) {
  estimate.earliest = estimate.latest = null;
  estimate.note = 'This delivery needs attention. Contact support.';
}

追跡すべき主要指標

予測精度を継続的に向上させるために、以下の指標をモニタリングしましょう。

指標目標値説明
予測的中率> 85%予測期間内に配達された割合
平均誤差< 1日日数の平均絶対誤差
顧客問い合わせ数減少傾向配達時期に関するWISMOコールの件数
信頼度の校正適切高信頼度の予測は95%以上の確率で正確であること

まとめ

リアルタイムの追跡イベントと過去のデータを組み合わせることで、強力な予測システムを構築できます。

  1. 収集 — すべての配送に対して追跡Webhookを登録する
  2. 分析 — イベントを処理し、ステータスと過去のデータを使って予測を計算する
  3. 表示 — 適切な信頼度レベルとともに予測を表示する
  4. 学習 — 実際の配達実績を記録して将来の予測を改善する
  5. 通知 — 予測が大幅に変更された場合にお客様に通知する

このシステムをWhereParcelのマルチキャリア追跡APIの上に構築することで、39社以上の配送業者にわたる一貫した追跡イベントを取得でき、グローバル規模で正確な予測を構築することが実現可能になります。プレイグラウンドで実際にお試しいただけます。

Webhookの設定について詳しくは、Webhook ベストプラクティスガイドをご覧ください。

ご希望の配送業者が見つかりませんか?リクエストいただければ迅速に対応いたします。

配送業者をリクエスト →

何か聞きたいことがあれば、気軽にどうぞ。 Discordに来てください — WhereParcelを作った開発者が直接メッセージを読んで返信します。ボットもチケットもなし。気軽に話しかけてください。

Discordに参加 → Slackに参加 →

タグ: #delivery-estimates #tracking #ux #tutorial #customer-experience