ガイドAPIリファレンス変更履歴
ガイド
  1. HERE Geocoding and Search API v7開発者ガイド
  2. HERE Geocoding and Search API v7エンドポイント
  3. Geocode

セカンダリユニットを使用して住所をジオコーディングする

このチュートリアルでは、セカンダリユニットを使用した住所のジオコーディングをサポートするために/geocodeエンドポイントに用意されているオプションについて説明します。

手順

/geocodeエンドポイントでは、顧客アプリケーションで建物、フロア (階)、スイート (ユニット) などのセカンダリユニット情報を活用できます。この情報が顧客アプリケーションに役立つさまざまなユースケースがあります。例としては、宅配でエンドユーザーが正確な建物、または建物内の正確な場所への配送を希望する場合などが考えられます。

マップデータでは、セカンダリユニットはマイクロポイント住所 (MPA) で表されます。ポイント住所と比べて、マイクロポイント住所はより詳細な住所とより高い座標精度を備えています。

HERE Geocoding and Searchは次の国でマイクロポイント住所をサポートしています：AUS、AUT、CAN、NZL、USA (PRI準州を含む)。

宅配向けのMPA - ユースケースA：リストからセカンダリユニットを選択する

📘

注

この機能はRESTRICTEDとしてリリースされています。「権限」を参照してください。

このユースケースでは、エンドユーザーが住所を検索しています。目的の住所が見つかると、アプリケーションにはその住所に関連付けられているすべてのユニット名が表示されます。

アプリケーションは、住所の位置情報とユニットの位置情報をそれぞれの名前とともに表示することもできます。

その後、エンドユーザーはユニットを目的地として選択できます。

このシナリオをサポートするため、HERE Geocoding and SearchにはshowRelated=MPA機能が用意されています。この機能により、/geocodeエンドポイントとlookupエンドポイントは建物、フロア(階数)、スイート(ユニット)など、この住所に関連付けられたマイクロポイント住所のリストを含むブロックをresultType=houseNumberとhouseNumberType=PAの結果項目に追加します。

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=2471+SW+58th+Mnr+Fort+Lauderdale+FL+33312
    &showRelated=MPA
    &apiKey={YOUR_API_KEY}

次のパラメーターを使用します。

  • showRelated - 一部のタイプのレスポンス項目を関連項目で充実させることができます。
  • q - 名前を入力します。
  • apiKey - APIキー。
📘

注

このリクエストはAPIキー認証を使用します。HEREプラットフォームの認証オプションの詳細については、「Identity & Access Management Guide」(IDとアクセス管理ガイド)を参照してください。

「2471 SW 58th Mnr」の住宅には、アクセスポイントは同じですが表示位置が異なる2つのユニット「E」と「W」があります。これらは、レスポンスの related ブロックに含まれます。

{
  "items": [
    {
      "title": "2471 SW 58th Mnr, Fort Lauderdale, FL 33312-6511, United States",
      "id": "here:af:streetsection:Ojge3i9Z2kNExmAnBAvyLB:CgcIBCDI1ps8EAEaBDI0NzE",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "2471 SW 58th Mnr, Fort Lauderdale, FL 33312-6511, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "FL",
        "state": "Florida",
        "county": "Broward",
        "city": "Fort Lauderdale",
        "street": "SW 58th Mnr",
        "postalCode": "33312-6511",
        "houseNumber": "2471"
      },
      "position": { "lat": 26.04932, "lng": -80.17407 },
      "access": [ { "lat": 26.04906, "lng": -80.17406 } ],
      "mapView": { "west": -80.17507, "south": 26.04842, "east": -80.17307, "north": 26.05022 },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "state": 1,
          "city": 1,
          "streets": [ 1 ],
          "houseNumber": 1,
          "postalCode": 1
        }
      },
      "related": [
        {
          "relationship": "MPA",
          "title": "2471 SW 58th Mnr Unit E, Fort Lauderdale, FL 33312-6511, United States",
          "id": "here:af:streetsection:Ojge3i9Z2kNExmAnBAvyLB:ChMIBCDI1ps8MgoKBggUIKW5fxAEEAEaBDI0NzE",
          "resultType": "houseNumber",
          "houseNumberType": "MPA",
          "position": { "lat": 26.04931, "lng": -80.17397 },
          "address": {
            "label": "2471 SW 58th Mnr Unit E, Fort Lauderdale, FL 33312-6511, United States",
            "unit": "E"
          }
        },
        {
          "relationship": "MPA",
          "title": "2471 SW 58th Mnr Unit W, Fort Lauderdale, FL 33312-6511, United States",
          "id": "here:af:streetsection:Ojge3i9Z2kNExmAnBAvyLB:ChMIBCDI1ps8MgoKBggUIJL8LRAEEAEaBDI0NzE",
          "resultType": "houseNumber",
          "houseNumberType": "MPA",
          "position": { "lat": 26.04931, "lng": -80.17406 },
          "address": {
            "label": "2471 SW 58th Mnr Unit W, Fort Lauderdale, FL 33312-6511, United States",
            "unit": "W"
          }
        }
      ]
    }
  ]
}

宅配向けのMPA - ユースケースB：住所と、ユニット名または住居番号の検索

📘

注

この機能はRESTRICTEDとしてリリースされています。「権限」を参照してください。

このユースケースでは、エンドユーザーはユニット名を含む住所を検索し、完全な住所、ユニット名、ユニットの位置情報が結果に表示されることを期待しています。

マイクロポイント住所の結果は特定のユースケースでのみ必要とされ、すべてのアプリケーションが使用するわけではないため、この機能はwith=MPAのパラメーターを使用して有効にする必要があります。このパラメーターを使用すると、geocodeエンドポイントは、クエリ内のセカンダリユニット情報を、マイクロポイント住所の住所、住居番号、ユニット名と照合しようとします。

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=2471+SW+58th+Mnr+Unit+E+Fort+Lauderdale+FL+33312
    &with=MPA
    &apiKey={YOUR_API_KEY}

次のパラメーターを使用します。

  • with - 特定の機能を有効にします。またはデフォルトでは有効になっていないか、提供されていない特定の種類の結果を考慮します。
  • q - 名前を入力します。
  • apiKey - APIキー。
📘

注

このリクエストはAPIキー認証を使用します。HEREプラットフォームの認証オプションの詳細については、「Identity & Access Management Guide」(IDとアクセス管理ガイド)を参照してください。

このリクエストの場合、/geocodeエンドポイントはresultType=houseNumberとhouseNumberType=MPAを含む結果を返します。

{
  "items": [
    {
      "title": "2471 SW 58th Mnr Unit E, Fort Lauderdale, FL 33312-6511, United States",
      "id": "here:af:streetsection:Ojge3i9Z2kNExmAnBAvyLB:ChUIBCDI1ps8MgwKCAgUILXouckCEAQQARoEMjQ3MQ",
      "resultType": "houseNumber",
      "houseNumberType": "MPA",
      "address": {
        "label": "2471 SW 58th Mnr Unit E, Fort Lauderdale, FL 33312-6511, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "FL",
        "state": "Florida",
        "county": "Broward",
        "city": "Fort Lauderdale",
        "street": "SW 58th Mnr",
        "postalCode": "33312-6511",
        "houseNumber": "2471",
        "unit": "E"
      },
      "position": { "lat": 26.04931, "lng": -80.17397 },
      "access": [{ "lat": 26.04906, "lng": -80.17396 }],
      "mapView": { "west": -80.17497, "south": 26.04841, "east": -80.17297, "north": 26.05021 },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "state": 1,
          "city": 1,
          "streets": [ 1 ],
          "houseNumber": 1,
          "postalCode": 1,
          "unit": 1
        }
      }
    }
  ]
}

結果項目のタイトル、住所ラベル、住所ブロックには、セカンダリユニット情報 (この場合は「Unit E」) が含まれます。

MPAを使用しない宅配向けのセカンダリユニット - ユースケースC：クエリからのセカンダリユニット情報の解析と正規化

このユースケースでは、エンドユーザーはユニット名を含む住所も検索し、完全な住所とユニット名が結果に表示されることを期待しています。ただし、検索意図がMPAサポートの対象外の国を対象としているか、顧客アプリケーションで制限付きMPA機能を使用していません。

この場合でも、/geocodeエンドポイントはクエリ内のセカンダリユニット情報を認識してそれを解析するため、クエリスコアは低下しません。

セカンダリユニット情報は、正確な座標がなくてもエンドユーザーにとって価値のある可能性があるため、次のように、顧客アプリケーションでは認識されたセカンダリユニットをレスポンスに含めるよう/geocodeエンドポイントにリクエストできます。

  • show=parsingパラメーターを使用したクエリと同じ方法。詳細については、「解析情報のリクエスト方法と使用方法」を参照してください。
  • または、show=secondaryUnitInfoパラメーターを使用して正規化された形式。
GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=2471+SW+58th+Mnr+Unit+E+Fort+Lauderdale+FL+33312
    &show=parsing%2CsecondaryUnitInfo
    &apiKey={YOUR_API_KEY}

次のパラメーターを使用します。

  • show - レスポンスに表示する追加フィールドを選択します。
    • parsing - /geocodeエンドポイントでは、リクエストをどのように解析したかについての情報を入手できます。
    • secondaryUnitInfo - /geocodeエンドポイントは、一致したユニット指定子ごとに、正規化されたユニットタイプとユニット値を含む追加のブロックを返します。
  • q - フリーテキストクエリを入力します。
  • apiKey - APIキー。
📘

注

このリクエストはAPIキー認証を使用します。HEREプラットフォームの認証オプションの詳細については、「Identity & Access Management Guide」(IDとアクセス管理ガイド)を参照してください。

このリクエストの場合、/geocodeエンドポイントはresultType=houseNumberとhouseNumberType=PAを含む結果を返します。結果項目のタイトル、住所ラベル、住所ブロックには、セカンダリユニット情報が含まれません。ただし、parsingブロックにはこれがクエリと同じ方法で格納されます。

結果項目には、同じセカンダリユニット情報が正規化された形式で表された新しいブロックsecondaryUnitInfoが含まれます。

{
  "items": [
    {
      "title": "2471 SW 58th Mnr, Fort Lauderdale, FL 33312-6511, United States",
      "id": "here:af:streetsection:Ojge3i9Z2kNExmAnBAvyLB:CgcIBCDI1ps8EAEaBDI0NzE",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "2471 SW 58th Mnr, Fort Lauderdale, FL 33312-6511, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "FL",
        "state": "Florida",
        "county": "Broward",
        "city": "Fort Lauderdale",
        "street": "SW 58th Mnr",
        "postalCode": "33312-6511",
        "houseNumber": "2471"
      },
      "position": { "lat": 26.04932, "lng": -80.17407 },
      "access": [{ "lat": 26.04906, "lng": -80.17406 }],
      "mapView": { "west": -80.17507, "south": 26.04842, "east": -80.17307, "north": 26.05022 },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "state": 1,
          "city": 1,
          "streets": [ 1 ],
          "houseNumber": 1,
          "postalCode": 1,
          "unit": 1
        }
      },
      "parsing": {
        "state": [{
            "start": 41,
            "end": 43,
            "value": "FL"
          }],
        ...
        "secondaryUnits": [{
            "start": 17,
            "end": 23,
            "value": "Unit+E"
          }]
      },
      "secondaryUnitInfo": [{
          "normalizedUnitType": "Unit",
          "unitValue": "e"
        }]
    }
  ]
}

HERE Geocoding and Searchでは、次の国で正規化されたセカンダリユニット情報をサポートしています：AUS、AUT、BRA、CAN、ESP、FRA、GBR、HKG、IDN、IND、MEX、NZL、TUR、TWN、USA (PRI準州を含む)

追加情報

/geocodeエンドポイントパラメーターの詳細については、「APIリファレンス」を参照してください。

4 日前の更新