セカンダリユニット情報を処理する

正確な住所の入力は、荷物の確実な配達やルートの効率性に直接影響を与えるため、配送および物流のワークフローにおいて極めて重要です。ドライバーは、多くの場合、エンドユーザーが入力した住所情報に頼ることになりますが、その住所にはアパートの部屋番号、スイート番号、またはユニット番号などの詳細なセカンダリユニット情報が含まれていることがよくあります。

このチュートリアルでは、/autocompleteエンドポイントを使用して、セカンダリユニット情報を含む住所の入力補完をサポートする方法について説明します。

/autocompleteエンドポイントは、サブ施設情報およびマイクロポイント住所 (MPA) をサポートすることで、アパートの部屋番号、スイート、ユニット番号などのセカンダリユニット (サブ施設) 情報に対応しています。

次のセクションでは、/autocompleteエンドポイントがよくある3つのシナリオをどのように処理するかを説明します。

配送先の住所に解決できないサブ施設情報が含まれている場合。

ユーザーが部屋番号やスイートなどのアパートまたはユニット情報を含むクエリを入力すると、/autocompleteエンドポイントは、照合 (マッチング) の際にその情報を解釈して利用しようとします。
サブ施設情報を照合できない場合、次のような理由が考えられます。

顧客アプリケーションでMPA機能を使用する権限がないか、リクエストで必要なパラメーターが設定されていない。
MPA情報がデータに含まれていない。
対象の国ではMPA機能がサポートされていない。

このような場合、/autocompleteエンドポイントは、クエリ内のユニット情報に関するトークンを検出して解析しますが、それらが一致することを必須とはしません。代わりに、住居番号と道路レベルの住所情報のみを使用して照合を続けます。

この動作により、サブ施設情報が原因で候補が返されなくなることを防ぐことができます。ユニット情報を解決できない場合でも、/autocompleteエンドポイントは住居番号レベルで適切な候補を返します。

これは、/autocompleteが通常、クエリ内のすべてのトークンが一致することを前提としているため重要です。ユニット情報については一致しなくてもよいようにすることで、候補の品質を維持し、候補の提示率が低下するのを防ぐことができます。特に、ユーザーがアパートの部屋番号やユニット番号から住所の入力を始めることが一般的な地域では、この動作が有効です。

結果：
クエリ内のユニット情報を解決できない場合でも、/autocompleteは、関連する住居番号の候補を返します。

リクエスト例：

GET /v1/autocomplete?q=unit 5/123 Geo&in=countryCode:AUS

レスポンス例：


{
   title: "Australia, NSW, 2000, The Rocks, 123 George St",
   id: here:af:streetsection:YQEnxljdtksncO8QD.lx2D:CggIBCDVxpjRAhABGgMxMjM,
   language: "en",
   resultType: "houseNumber",
   houseNumberType: "PA",
   address: {
      label: "123 George St, The Rocks NSW 2000, Australia",
      countryCode: "AUS",
      countryName: "Australia",
      stateCode: "NSW",
      state: "New South Wales",
      city: "Sydney",
      district: "The Rocks",
      street: "George St",
      postalCode: "2000",
      houseNumber: "123"
   },

この場合、サブ施設情報を解決できなくても、
配送先は正しい建物に関連付けられています。

配送先住所にマイクロポイント住所と一致するアパートやユニットの情報が含まれている場合

ユーザーが部屋番号やスイートなどのアパートまたはユニット情報を含むクエリを入力した場合、マイクロポイント住所 (MPA) のサポートが有効になっていれば、/autocompleteエンドポイントはこの情報を利用することができます。顧客のアプリケーションは、MPAを利用するための認可を受け、パラメーターにwith=MPAを設定する必要があります。

この場合、/autocompleteはクエリ内のユニット情報に関連する部分を検出して解析し、対応する住居番号に関連付けられたMPAデータと照合しようとします。

一致が見つかった場合、/autocompleteはマイクロポイント (ユニット) レベルの候補を返し、より正確な住所を提供します。

一致が見つからない場合、標準の動作にフォールバックします。サブ施設情報は無視され、レスポンスには住居番号レベルの候補が含まれます。このフォールバックにより、ユニットレベルのデータが存在しない場合でも一貫性のある結果が保証され、候補の生成が妨げられる事態を回避できます。

結果：
一致が見つかった場合、/autocompleteは、マイクロポイント住所レベルの候補を返します。一致しない場合は、最初のシナリオで説明したとおり、標準の住居番号レベルの候補を返します。

MPAに一致する場合のリクエスト例：

GET /v1/autocomplete?q=101/2 Gentian Dr Aru&in=countryCode:AUS&with=MPA

レスポンス例：


{
   title: "Australia, QLD, 4214, Arundel, 101/2 Gentian Dr",
   id: here:af:streetsection:jZUaMY6NNdXKbdHRhGC33C:ChYIBCDipMbWAjIMCggIFCDgi5ygAxAEEAEaATI,
   language: "en",
   resultType: "houseNumber",
   houseNumberType: "MPA",
   address: {
      label: "101/2 Gentian Dr, Arundel QLD 4214, Australia",
      countryCode: "AUS",
      countryName: "Australia",
      stateCode: "QLD",
      state: "Queensland",
      city: "Gold Coast",
      district: "Arundel",
      street: "Gentian Dr",
      postalCode: "4214",
      houseNumber: "2",
      unit: "101"
   }

この結果は、解決済みのMPAを表しており、
ユニットレベルの配送に適しています。

建物から利用可能なマイクロポイント住所を検出する

一部のアプリケーションでは、ユーザーによるサブプレミス情報の入力を想定していませんが、それでもアプリケーション側で次の対応を行いたい場合があります。

指定した住所にユニットレベルの住所がさらに存在することを示す。
ユーザーが候補を選択した場合、それらの住所を検出できるようにする。

このユースケースでは、/autocompleteは次のパラメーターを提供しています：
show=hasRelatedMPA

各ポイント住所候補について、/autocompleteは次を示すフラグを返します。

その場所でMPAが利用可能かどうか
/autocompleteは、次のような事態を回避するため、MPAそのものは返しません。
- 候補数が過剰になること
- 候補リストのパフォーマンスが低下すること

実際のマイクロポイント住所を取得は、次のように行います。

/lookupエンドポイントを使用する
次のパラメーターを指定する：showRelated=MPA
(注：このパラメーターは利用が制限されており、使用には認証が必要です。

結果：

/autocompleteはMPAデータが利用可能かどうかを示します。
/lookupはサブ施設住所の全リストを取得します。

リクエスト例：

GET /v1/autocomplete?q=95-99 Tram R&show=hasRelatedMPA

レスポンス例：


{
  "title": "95-99 Tram Rd, Doncaster VIC 3108, Australia",
  "id": "here:af:streetsection:ZV8woXvI1T787UC1-.w-VB:CggIBCCMg-GgARABGgU5NS05OQ",
  "resultType": "houseNumber",
  ......
  "hasRelatedMPA": true
}

hasRelatedMPAがtrueの場合、返されたidを/lookupとともに使用することで、関連するすべてのMPAを取得し、住所を確定できます。

idを指定したLookupリクエストの例：

GET /v1/lookup?id=here:af:streetsection:ZV8woXvI1T787UC1-.w-VB:CggIBCCMg-GgARABGgU5NS05OQ&showRelated=MPA

レスポンス例：

{
   related: [
      {
         relationship: "MPA",
         title: "1/95-99 Tram Rd, Doncaster VIC 3108, Australia",
         id: here:af:streetsection:ZV8woXvI1T787UC1-.w-VB:ChYIBCCMg-GgATIMCggIFCCmprigAxAEEAEaBTk1LTk5,
         resultType: "houseNumber",
         houseNumberType: "MPA",
         address: {
            label: "1/95-99 Tram Rd, Doncaster VIC 3108, Australia",
            unit: "1"
         },
         position: {
            lat: -37.78871,
            lng: 145.12478
         }
      },
      {
         relationship: "MPA",
         title: "10/95-99 Tram Rd, Doncaster VIC 3108, Australia",
         id: here:af:streetsection:ZV8woXvI1T787UC1-.w-VB:ChYIBCCMg-GgATIMCggIFCC15b-gAxAEEAEaBTk1LTk5,
         resultType: "houseNumber",
         houseNumberType: "MPA",
         address: {
            label: "10/95-99 Tram Rd, Doncaster VIC 3108, Australia",
            unit: "10"
         },
         position: {
            lat: -37.78871,
            lng: 145.12478
         }
      },
      ......
	]
}

提供状況と制限

フィーチャー	サポートされている国	認証が必須
サブ施設の許容範囲 (`/autocomplete`のシナリオ1)	AUS	いいえ
MPAの照合 (`/autocomplete`のシナリオ2)	AUS	はい
show=hasRelatedMPA (`/autocomplete`のシナリオ3)	AUT、AUS、BRA、CAN、NZL、USA (+プエルトリコ)	いいえ
showRelated=MPA (`/lookup`)	AUT、AUS、BRA、CAN、NZL、USA (+プエルトリコ)	はい