HERE Geocoding and Search API v7での政治的見解の扱い

HERE Geocoding and Searchは未解決の係争地を特定の国の観点から表示できます。デフォルトでは、HERE Geocoding and Searchはこのような係争中の地域について、HERE Geopolitical Board (HERE 地政学委員会)によって定義された中立的な見解を示します。

顧客アプリケーションはpoliticalViewパラメーターを設定して、政治的見解を選択できます。このパラメーターでは ISO 3166-1 alpha-3 の大文字のみの国コードを 1 つ使用できます。politicalViewは係争地内のすべての結果タイプに影響を及ぼします。

📘
注：
次の国では、HERE Geocoding and SearchはISO-3166コードとは異なるコードを使用しています。XSB-BSB、XCY-CUN、XGS-GAS、XGI-GRI、XKO-KOS、XKI-KRI、XNC-NCY、XPI-PLI、XSO-SAS、XSI-SPI。

たとえば、現在対応している政治的見解の1つに、フォークランド諸島のStanleyに対するアルゼンチンの見解があります。デフォルトでは、HERE Geocoding & SearchはStanleyをフォークランド諸島の一部として表示します。HERE Geocoding and Searchではアルゼンチン市場をターゲットとする顧客アプリケーションの場合、アルゼンチンの政治的見解を設定して、Stanleyをアルゼンチンの一部として表示できます。

現在対応している政治的見解と係争地の全リストは、「対応している政治的見解」を参照してください。対応している政治的見解のリストは、次のHERE Geocoding and Searchリリースで拡張されます。

関連するエンドポイント： /geocode /revgeocode /autocomplete、 /discover、 /autosuggest、 /lookup、 /browse、

次の例では、ユーザーがpoliticalViewパラメーターを指定せずにフォークランド諸島のStanleyにあるDaiary Paddock Roadを検索しています。

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=dairy paddock road
    &at=-51.7849655,-58.9185672
    &lang=en-US
    &apiKey={YOUR_API_KEY}

HERE Geocoding and SearchはDaiary Paddock Roadをフォークランド諸島の一部として示す結果を返します。

{
    "items": [
        {
            "title": "Dairy Paddock Road, Stanley, Falkland Islands",
            "id": "here:af:street:qiUkYNPzbysXsXmMMZcLtB",
            "resultType": "street",
            "address": {
                "label": "Dairy Paddock Road, Stanley, Falkland Islands",
                "countryCode": "FLK",
                "countryName": "Falkland Islands",
                "county": "Falkland Islands",
                "city": "Stanley",
                "street": "Dairy Paddock Road"
            },
            "position": {
                "lat": -51.69499,
                "lng": -57.86533
            },
            "distance": 73208,
            "mapView": {
                "west": -57.86554,
                "south": -51.69655,
                "east": -57.86504,
                "north": -51.69344
            },
            "scoring": {
                "queryScore": 1.0,
                "fieldScore": {
                    "streets": [
                        1.0
                    ]
                }
            }
        }
    ]
}

同じクエリでpoliticalViewパラメーターをARGに設定すると次のようになります。

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=dairy paddock road
    &at=-51.7849655,-58.9185672
    &lang=en-US
    &politicalView=ARG
    &apiKey={YOUR_API_KEY}

HERE Geocoding and SearchはStanleyにあるDairy Paddock Roadをアルゼンチンの一部として示す結果を返します。

{
    "items": [
        {
            "title": "Dairy Paddock Road, Puerto Argentino, Argentina",
            "id": "here:af:street:RTR6gs71ARSRWkMWTagJHD",
            "politicalView": "ARG",
            "resultType": "street",
            "address": {
                "label": "Dairy Paddock Road, Puerto Argentino, Argentina",
                "countryCode": "ARG",
                "countryName": "Argentina",
                "stateCode": "TF",
                "state": "Land of Fire, Ant. and S. Atl. Is.",
                "county": "Islas Malvinas (Arg.)",
                "city": "Puerto Argentino",
                "street": "Dairy Paddock Road"
            },
            "position": {
                "lat": -51.69499,
                "lng": -57.86533
            },
            "distance": 73208,
            "mapView": {
                "west": -57.86554,
                "south": -51.69655,
                "east": -57.86504,
                "north": -51.69344
            },
            "scoring": {
                "queryScore": 1.0,
                "fieldScore": {
                    "streets": [
                        1.0
                    ]
                }
            }
        }
    ]
}

3文字の国コードが有効で、HERE Geocoding and Searchにより固有の政治的見解が設定されていないものは、デフォルトの見解にフォールバックします。たとえば、politicalView=USAまたはpoliticalView=FRAはどのような場合でもレスポンスに影響を及ぼしません。

このフォールバックロジックによる誤解を避けるために、HERE Geocoding and Searchでは各結果項目のレスポンスに、結果項目の実際の政治的見解を示す新しいフィールドpoliticalViewが含まれています。リクエストにpoliticalViewパラメーターが含まれている場合にのみ、レスポンスに含まれます。

現在、politicalView フィールドでサポートされている値は default と ARG です。

上の 2 つの例のうち最初の例では、顧客アプリケーションで politicalView パラメーターを設定していません。そのため、結果項目にはpoliticalViewフィールドが含まれません。 2つ目の例では、結果項目にアルゼンチンの政治的見解が含まれているため、politicalViewフィールドがレスポンスに含まれ、ARGに設定されます。

同じクエリでpoliticalViewパラメーターをDEUに設定すると次のようになります。これは有効な値ですが、フォークランド諸島に関する固有の政治的見解がありません。

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=dairy paddock road
    &at=-51.7849655,-58.9185672
    &lang=en-US
    &politicalView=DEU
    &apiKey={YOUR_API_KEY}

HERE Geocoding and Searchはデフォルトの政治的見解として、StanleyにあるDaiary Paddock Roadをフォークランド諸島の一部として示す結果を返します。結果項目にはdefaultに設定されたpoliticalViewフィールドが含まれます。

{
    "items": [
        {
            "title": "Dairy Paddock Road, Stanley, Falkland Islands",
            "id": "here:af:street:qiUkYNPzbysXsXmMMZcLtB",
            "politicalView": "default",
            "resultType": "street",
            "address": {
                "label": "Dairy Paddock Road, Stanley, Falkland Islands",
                "countryCode": "FLK",
                "countryName": "Falkland Islands",
                "county": "Falkland Islands",
                "city": "Stanley",
                "street": "Dairy Paddock Road"
            },
            "position": {
                "lat": -51.69499,
                "lng": -57.86533
            },
            "distance": 73208,
            "mapView": {
                "west": -57.86554,
                "south": -51.69655,
                "east": -57.86504,
                "north": -51.69344
            },
            "scoring": {
                "queryScore": 1.0,
                "fieldScore": {
                    "streets": [
                        1.0
                    ]
                }
            }
        }
    ]
}

politicalViewパラメーターに認められていない値が含まれている場合、HERE Geocoding and Searchは「400」エラーコードを返します。認められていない値の例： politicalView=Argentina politicalView=arg politicalView=default politicalView=UK,ARG

politicalView パラメーターを使用した Lookup by ID

係争地では同じ住所、番地、行政区画でも政治的見解が異なれば、それぞれに id 値が異なる場合があります。

/lookupエンドポイントにクエリする際、顧客アプリケーションは対応するid値とpoliticalView値を使用する必要があります。値が対応していない場合、/lookupエンドポイントはエラーコード404 (Not Found): Location ID conflicts with political viewを返します。

これは場所の結果には当てはまりません。場所は政治的見解から独立しており、同じ id を持っています。/lookup エンドポイントはこの場所を /lookup 呼び出しの politicalView パラメーターにより指定された政治的見解の行政構造で返します。

関連するエンドポイント：/lookup