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.
Related endpoints: /geocode
/revgeocode
/autocomplete
, /discover
, /autosuggest
, /lookup
, /browse
,
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
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
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
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
href
in the first result item contains the filed politicalView=RUS
:
{
"items": [
{
"title": "restaurants",
"id": "here:cm:ontology:restaurant",
"resultType": "categoryQuery",
"href": "http:
&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