郵便番号の市区町村情報を入力する

HERE Geocoding and Searchの/autocompleteおよび/geocodeエンドポイントには、任意パラメーターpostalCodeModeがあり、1つの郵便番号が複数の地区や都市エリアにまたがる場合に、詳細な結果を取得できます。デフォルトでは、結果は1つだけ返されます。そのため、地区名や都市名が空白になったり、デフォルト名が使用されたりして、関連する詳細情報が省略される可能性があります。

サポートされている値の説明：

cityLookup：1つの郵便番号が複数の都市にまたがる場合、cityLookupはその郵便番号と対応する都市名のすべての組み合わせを返します。
districtLookup：1つの郵便番号が複数の地区(同一都市内または複数都市)にまたがる場合、districtLookupはその郵便番号と対応する地区名および都市名のすべての組み合わせを返します。

たとえば、オーストラリアの郵便番号「3977」は、Devon MeadowsやCannons Creekといった複数の町に加え、Cranbourne、Skye、Botanic RidgeなどのMelbourneの複数の郊外(地区)をカバーしています。

次の例では、ユーザーは/autocompleteエンドポイントを使用してオーストラリアの郵便番号を検索しています。同じ郵便番号が複数の国に存在する可能性があるため、in=countryCode:AUSパラメーターを使用して国フィルターを適用することをお勧めします。

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=3977
    &in=countryCode%3AAUS
    &limit=20
    &apiKey={YOUR_API_KEY}

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

q - 名前を入力します。
In - 地理的エリア内を検索します。結果が指定したエリア内にある場合、結果が返されます。
limit - 返される結果の最大数。
apiKey - APIキー。

デフォルトモードでは、HERE Geocoding and Searchの/autocompleteエンドポイントは、1つの郵便番号結果のみを返し、地区や都市のフィールドは空のままになります。

{
  "items": [
    {
      "title": "Australia, VIC, 3977",
      "id": "here:cm:namedplace:25711684",
      "language": "en",
      "resultType": "locality",
      "localityType": "postalCode",
      "address": {
        "label": "3977, Victoria, Australia",
        "countryCode": "AUS",
        "countryName": "Australia",
        "stateCode": "VIC",
        "state": "Victoria",
        "postalCode": "3977"
      },
      "highlights": {
        "title": [
          { "start": 16,
            "end": 20 }],
        "address": {
          "label": [
            { "start": 0,
              "end": 4 }],
          "postalCode": [
            { "start": 0,
              "end": 4 }]
        }
      }
    }
  ]
}

同じクエリにpostalCodeMode=cityLookupパラメーターを設定した場合：

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=3977
    &in=countryCode%3AAUS
    &postalCodeMode=cityLookup
    &limit=20
    &apiKey={YOUR_API_KEY}

postalCodeMode=cityLookupパラメーターを使用すると、HERE Geocoding and Searchの/autocompleteエンドポイントは、郵便番号が重複する都市または町ごとに1件ずつ、合計3件の郵便番号結果を返し、各都市の人口順に並べ替えます。

{
  "items": [
    {
      "title": "Australia, VIC, 3977",
      "id": "here:cm:namedplace:25711684-1469261839",
      "language": "en",
      "resultType": "locality",
      "localityType": "postalCode",
      "address": {
        "label": "3977, Melbourne, Victoria, Australia",
        ...
        "city": "Melbourne",
        "postalCode": "3977"
      },
      ...
    },
    {
      "title": "Australia, VIC, 3977",
      "id": "here:cm:namedplace:25711684-1469258642",
      "language": "en",
      "resultType": "locality",
      "localityType": "postalCode",
      "address": {
        "label": "3977, Devon Meadows, Victoria, Australia",
        ...
        "city": "Devon Meadows",
        "postalCode": "3977"
      },
      ...
    },
    {
      "title": "Australia, VIC, 3977",
      "id": "here:cm:namedplace:25711684-1469259583",
      "language": "en",
      "resultType": "locality",
      "localityType": "postalCode",
      "address": {
        "label": "3977, Cannons Creek, Victoria, Australia",
        ...
        "city": "Cannons Creek",
        "postalCode": "3977"
      },
      ...
    }
  ]
}

postalCodeModeパラメーターを使用する場合は、国フィルターの適用がより重要になります。これは、各国に複数の郵便番号結果が存在する可能性があり、それらは国別ではなく都市の人口順に並べ替えられるためです。

オーストラリアでは、住所表記や目的地検索に地区名が一般的に使用されます。そのため、エンドユーザーは郵便番号に関連付けられた地区名も確認したい場合があります。

同じクエリにpostalCodeMode=districtLookupパラメーターを設定した場合：

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=3977
    &in=countryCode%3AAUS
    &postalCodeMode=districtLookup
    &limit=20
    &apiKey={YOUR_API_KEY}

postalCodeMode=districtLookupパラメーターを使用すると、/autocompleteエンドポイントはより多くの郵便番号結果を返します。これは、郵便番号が都市や町だけでなく、地区とも重複する場合を考慮するためです。

Melbourne市には複数の地区(郊外)があり、そのうち9つが郵便番号「3977」を共有しています。postalCodeMode=cityLookupの場合、/autocompleteエンドポイントは、Melbourne市の郵便番号「3977」に対して1件の結果のみを返します。一方、postalCodeMode=districtLookupの場合、各郊外に1件ずつ、合計9件の結果を返します。
Cannons Creekという町には、「Cannons Creek」という地区が1つだけ存在します。postalCodeMode=districtLookupの場合、/autocompleteエンドポイントは引き続き1件の結果のみを返しますが、結果に地区名である「Cannons Creek」が含まれるようになりました。
Devon Meadowsという町は人口が比較的少ないため、HERE Map Contentではビルドアップエリアが定義されておらず、地区としてコード化されていません。そのため、postalCodeMode=districtLookupを使用しても、/autocompleteエンドポイントは引き続き都市名「Devon Meadows」を含む郵便番号を返し、地区フィールドは空のままになります。

{
  "items": [
    {
      "title": "Australia, VIC, 3977, Cranbourne",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Cranbourne East",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne East", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Cranbourne West",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne West", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Cranbourne North",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne North", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Cranbourne South",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne South", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Skye",
      ...
      "address": { ..., "city": "Melbourne", district": "Skye", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Botanic Ridge",
      ...
      "address": { ..., "city": "Melbourne", "district": "Botanic Ridge", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Sandhurst",
      ...
      "address": { ..., "city": "Melbourne", "district": "Sandhurst", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Cannons Creek",
      ...
      "address": { ..., "city": "Cannons Creek", "district": "Cannons Creek", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Junction Village",
      ...
      "address": { ..., "city": "Melbourne", "district": "Junction Village", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Devon Meadows",
      ...
      "address": { ..., "city": "Devon Meadows", ...
      },
      ...
    }
  ]
}

postalCodeMode=districtLookupを使用する場合、クエリに都市名を追加すると、その都市に郵便番号結果が限定されると考えられがちです。これは一般的には当てはまりますが、郵便番号と都市名を組み合わせたクエリの意図は必ずしも明確ではありません。たとえば、ユーザーは大都市内の郵便番号を探している場合もあれば、同名の町や村を区別しようとしている場合もあります。/autocompleteエンドポイントの場合、ユーザーは都市名で始まる道路名を郵便番号で検索している場合もあります。

HERE Geocoding and Searchエンドポイントは、ケースバイケースで意図を判断し、最も正確な結果を選択します。

特定の郵便番号に関連付けられたすべての都市または地区のリストを取得する特殊な郵便番号モードでは、typesフィルターのtypes=postalCodeを使用することをお勧めします。

同じクエリにpostalCodeMode=districtLookupを設定し、都市名「Melbourne」を追加し、さらにtypes=postalCodeフィルターを適用した場合：

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=3977+Melbourne
    &in=countryCode%3AAUS
    &postalCodeMode=districtLookup
    &types=postalCode
    &limit=20
    &apiKey={YOUR_API_KEY}

このクエリでは、/autocompleteエンドポイントは、郵便番号が重複するMelbourne市の各郊外に1件ずつ、合計9件の郵便番号結果を返します。なお、クエリに都市名が含まれているため、/autocompleteエンドポイントは結果タイトルにもその都市名を含めます。

{
  "items": [
    {
      "title": "Australia, VIC, 3977, Melbourne, Cranbourne",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Cranbourne East",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne East", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Cranbourne West",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne West", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Cranbourne North",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne North", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Cranbourne South",
      ...
      "address": { ..., "city": "Melbourne", "district": "Cranbourne South", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Skye",
      ...
      "address": { ..., "city": "Melbourne",  "district": "Skye", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Botanic Ridge",
      ...
      "address": { ..., "city": "Melbourne", "district": "Botanic Ridge", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Sandhurst",
      ...
      "address": { ..., "city": "Melbourne", "district": "Sandhurst", ... },
      ...
    },
    {
      "title": "Australia, VIC, 3977, Melbourne, Junction Village",
      ...
      "address": { ..., "city": "Melbourne", "district": "Junction Village", ...
      },
      ...
    }
  ]
}