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 may choose a political view by setting 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 Russian view on Crimea. HERE Geocoding and Search represents it by default as part of Ukraine. For customer applications that target the Russian market, HERE Geocoding and Search allows setting Russian political view with Crimea region shown as part of Russia.

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 city Sevastopol without politicalView parameter.

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=Sevastopol
    &lang=en-US

Authorization: Bearer [your token]

HERE Geocoding and Search returns the result with city Sevastopol as part of Ukraine:

{
  "items": [
    {
      "title": "Sevastopol, Ukraine",
      "id": "here:cm:namedplace:23675160",
      "resultType": "locality",
      "localityType": "city",
      "address": {
        "label": "Sevastopol, Ukraine",
        "countryCode": "UKR",
        "countryName": "Ukraine",
        "county": "Sevastopol",
        "city": "Sevastopol",
        "postalCode": "299011"
      },
      "position": {
        "lat": 44.60527,
        "lng": 33.52729
      },
      "mapView": {
        "west": 33.37855,
        "south": 44.3873,
        "east": 33.92137,
        "north": 44.84141
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "city": 1
        }
      }
    }
  ]
}

The same query with politicalView parameter set to RUS.

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=Sevastopol
    &lang=en-US
    &politicalView=RUS

Authorization: Bearer [your token]

HERE Geocoding and Search returns the result with city Sevastopol under administrative structure of Russia:

{
  "items": [
    {
      "title": "Sevastopol, Southern Federal District, Russia",
      "id": "here:cm:namedplace:26937685",
      "politicalView": "RUS",
      "resultType": "locality",
      "localityType": "city",
      "address": {
        "label": "Sevastopol, Southern Federal District, Russia",
        "countryCode": "RUS",
        "countryName": "Russia",
        "state": "Southern Federal District",
        "county": "Sevastopol",
        "city": "Sevastopol"
      },
      "position": {
        "lat": 44.60527,
        "lng": 33.52729
      },
      "mapView": {
        "west": 33.37855,
        "south": 44.3873,
        "east": 33.92137,
        "north": 44.84141
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "city": 1
        }
      }
    }
  ]
}

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 a response in any way.

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

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 Russian political view and politicalView field is present in the response and is set to RUS.

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

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=Sevastopol
    &lang=en-US
    &politicalView=DEU

Authorization: Bearer [your token]

HERE Geocoding and Search returns the default political view on city Sevastopol under administrative structure of Ukraine. The result item include the politicalView field set to default:

{
  "items": [
    {
      "title": "Sevastopol, Ukraine",
      "id": "here:cm:namedplace:23675160",
      "politicalView": "default",
      "resultType": "locality",
      "localityType": "city",
      "address": {
        "label": "Sevastopol, Ukraine",
        "countryCode": "UKR",
        "countryName": "Ukraine",
        "county": "Sevastopol",
        "city": "Sevastopol",
        "postalCode": "299011"
      },
      "position": {
        "lat": 44.60527,
        "lng": 33.52729
      },
      "mapView": {
        "west": 33.37855,
        "south": 44.3873,
        "east": 33.92137,
        "north": 44.84141
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "city": 1
        }
      }
    }
  ]
}

For not accepted values of the politicalView parameter the GS7 responds with "400" error code. Examples of not accepted values: politicalView=Russian politicalView=rus politicalView=default politicalView=RUS,TUR

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 in query suggestions

Query suggestions are meant to be used by application developers to build follow-up queries. For categoryQuery or chainQuery result items HERE Geocoding and Search constructs the follow-up query URLs with the same value of politicalView parameter as the original query:

Restaurants query suggestion in Sevastopol with politicalView=RUS:

GET https://autosuggest.search.hereapi.com/v1/
    autosuggest
    ?q=restaurants
    &at=44.6049598%2C33.5258536
    &lang=en-US
    &limit=2
    &politicalView=RUS

Authorization: Bearer [your token]

href in the first result item contains the filed politicalView=RUS:

{
  "items": [
    {
      "title": "restaurants",
      "id": "here:cm:ontology:restaurant",
      "resultType": "categoryQuery",
      "href": "http://ci.opensearch.dev.api.here.com/v1/discover?politicalView=RUS
            &at=44.60496%2C33.52585&q=restaurants&_ontology=restaurant&lang=en-US",
      "highlights": {
        "title": [
          {
            "start": 0,
            "end": 11
          }
        ]
      }
    },
    {
      "title": "Vkus Gretsii",
      "id": "here:pds:place:804sxzvf-f471573ff08e43cea850c6182ccd0234",
      "politicalView": "RUS",
      "ontologyId": "here:cm:ontology:restaurant",
      "resultType": "place",
      "address": {
        "label": "Vkus Gretsii, Lenina vulytsia 60, Sevastopol, Russia"
      },
      "position": {
        "lat": 44.60491,
        "lng": 33.52691
      },
      "access": [
        {
          "lat": 44.60483,
          "lng": 33.52716
        }
      ],
      "distance": 84,
      "categories": [
        {
          "id": "100-1000-0007",
          "name": "Cafeteria",
          "primary": true
        }
      ],
      "highlights": {
        "title": [],
        "address": {
          "label": []
        }
      }
    }
  ],
  "queryTerms": []
}

Related endpoint: /autosuggest

Political views

Political views

Lookup by id with politicalView parameter

Political views in query suggestions

results matching ""

No results matching ""

Developer