Political views

HERE Geocoding and Search allows showing territories with unresolved claims through the point of view of particular countries. By default, HERE Geocoding and Search shows for such disputed territories a neutral view as defined by HERE Geopolitical Board.

The customer application can choose a political view by setting the politicalView parameter. This parameter accepts all uppercase single ISO 3166-1 alpha-3 country codes. The politicalView impacts all the result types within the disputed territories.

For example, one of the currently supported political views is the Argentinian view on Stanley in the Falkland Islands. HERE Geocoding and Search represents it by default as part of the Falkland Islands. For customer applications that target the Argentinian market, HERE Geocoding and Search allows setting an Argentinian political view with Stanley shown as part of Argentina.

The complete list of currently supported political views and disputed territories can be found at Supported Political Views. We will extend the list of the supported political views with the next HERE Geocoding and Search releases.

In the following example, the user is searching for Dairy Paddock Road, Stanley in the Falkland Islands without the politicalView parameter.

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 returns the result with Dairy Paddock Road shown as being part of the Falkland Islands:

{
    "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
                    ]
                }
            }
        }
    ]
}

The same query with politicalView parameter set to 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 returns the result with the Dairy Paddock Road, Stanley being part of Argentina:

{
    "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
                    ]
                }
            }
        }
    ]
}

For any valid 3 letter country code, for which HERE Geocoding and Search does not have dedicated political view, it falls back to the default view. For example, politicalView=USA or politicalView=FRA does not impact the response in any way.

To avoid misunderstanding due to this fallback logic, HERE Geocoding and Search includes in the response for each result item, a new field politicalView with the actual political view of the result item. It is included in the response only if the request contains the politicalView parameter. Currently, supported values of the politicalView field are default and ARG.

In the first of the two examples above, the customer application does not set the politicalView parameter. Therefore, the result item does not include the politicalView field In the second example, the result item has the Argentinian political view and politicalView field is present in the response and is set to ARG.

The same query with politicalView parameter set to DEU, which is valid value but does not have dedicated political view on the Falkland Islands:

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 returns the default political view on Dairy Paddock Road, Stanley as part of the Falkland Islands. The result item includes the politicalView field set to default:

{
    "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
                    ]
                }
            }
        }
    ]
}

For not accepted values of the politicalView parameter the GS7 responds with "400" error code. Examples of not accepted values: politicalView=Argentina politicalView=arg politicalView=default politicalView=UK,ARG

Lookup by id with politicalView parameter

Note that the same address, street or administrative place in disputed territories in different political views may have different id values. While querying /lookup endpoint the customer application needs to assure to use the matching id and politicalView values. Otherwise /lookup endpoint responds with error code 404 (Not Found): Location ID conflicts with political view. This is different for place results. A place has the same id independent on the political view. The /lookup endpoint will return this place with administrative structure of the political view specified by politicalView parameter in the /lookup call.

Related endpoint: /lookup

Political views

Political views

Lookup by id with politicalView parameter

results matching ""

No results matching ""

Developer