| additionaldata | Key-value pairs that provide additional input to requests. See Additional Data Parameter for a full list. Key and value are separated using a ,. Multiple key-value pairs are separated using a ;: additionaldata=<Key1>,<Value1>;<Key2>,<Value2>;...
Example: additionaldata=PreserveUnitDesignators,true;
IncludeZipAddon,true
|
addressattributes | A comma-separated list whose elements are present in the response data. Enumeration [country, state, county, city, district, subdistrict, street, houseNumber, postalCode, addressLines, additionalData] Abbreviated forms: [ctr, sta, cty, cit, dis, sdi, str, hnr, pst, aln, add] Default in response: All except addressLines. Note: The value names are case-sensitive. |
| app_id | xs:string A 20 byte Base64 URL-safe encoded string used for the authentication of the client application. You must include an app_id and app_code with every request. For more information, see the Identity & Access Management Developer Guide. |
| app_code | xs:string A 20 byte Base64 URL-safe encoded string used for the authentication of the client application. You must include an app_id and app_code with every request. For more information, see the Identity & Access Management Developer Guide. |
app_id | xs:string A 20-byte Base64 URL-safe encoded string used in one of the available authentication options for the Geocoder API. If you use the app ID/app code option, you need to include an app_id and app_code with every request. For more information, see the Identity & Access Management Developer Guide. |
app_code | xs:string A 20-byte Base64 URL-safe encoded string used for the authentication of the client application. If you use the app ID/app code option, you need to include an app_id and app_code with every request. For more information, see the Identity & Access Management Developer Guide. |
apiKey | xs:string A 43-byte Base64 URL-safe encoded string used for the authentication of the client application. As a logged in user, you can generate it at https://here-tech.skawa.fun/projects. API Keys never expire but you can invalidate your API Keys at any time. You cannot have more than two API Keys for one app at the same time. You must include an apiKey with every request. For more information, see the Identity & Access Management Developer Guide. |
| bbox | see also GeoBoundingBoxType A type of Spatial Filter. A spatial filter limits the search for any other attributes in the request. A bounding box bbox is specified by two latitude / longitude pairs; the first pair defines the top left corner of the bounding box, the second set the lower right. The bbox search is currently similar to mapview but it is not extended. Relevant global results are also returned. bbox=<TopLeft.Latitude>,<TopLeft.Longitude>;
<BottomRight.Latitude>,<BottomRight.Longitude>
Example: bbox=41.9085286,-87.6762943;41.8682739,-87.6041965 |
| categoryids | xs:integer Limit landmark results to one or more categories. Examples: - Highway exits: 116
- Airports: 4581
- Tourist attractions: 7999
|
| city | xs:string A country specific mapping is required. Example, - USA: City
- Germany: Gemeinde
|
| country | xs:string, exact match Specify the country or list of countries using the country code (3 bytes, ISO 3166-1-alpha-3) or the country name. This is a strict filter. Results are restricted to the specified country or countries. Note: To avoid ambiguity we recommend to specify the country with the 3-letter ISO code and not with the spelled out country name. With names there is a higher risk of misspells and also not all language translations for all countries are supported. |
| countryfocus | xs:string, exact match, single ISO 3166-1-alpha-3 country code Results from the specified country are preferred. This is a soft filter. Spelled out country names are not supported for country focus. - If both hard country filter and soft country focus parameter are set in the request the country filter takes precedence over the focus. This means results are limited to countries specified with country filter.
-
bbox or mapview filter take precedence over the country focus if there is a conflict. |
| county | xs:string Second subdivision level below the country. Depending on the admin hierarchy in a country this level might not be applicable. Example, - USA: County
- Germany: Kreis
|
| district | xs:string Subdivision level below the city. Depending on the admin hierarchy in a country this level might not be applicable. Example, - USA: n/a
- Germany: Ortsteil
|
| gen | xs:int The gen parameter enables or disables backward incompatible behavior in the API. -
gen=0 default behavior -
gen=1 - If a reverse geocoding request for an address finds no address or street within the specified radius, the area information is returned instead. If
gen=0, the results with a 10,000 meter radius are returned. - Result
MatchLevel for intersection matches is intersection. With gen=0, the MatchLevel for intersection matches is street. -
gen=2 - Includes
gen=1 functionality. - Reverse geocode area response includes
DispalyPosition whose value is the area display position (for example the center of the area). For gen<2, DisplayPosition mirrors the point from the request. - If the request specifies
locationattributes=(one of mr, mapReference, all), the response element MapReference contains the map version. For gen<2, MapReference does not contain the map version. -
gen=3 - Includes
gen=2 functionality. - Reverse geocoding address results include distinct display and navigation positions. With
gen<3, address results from reverse geocoding show a display position which is always the same as the navigation position. With gen=3 this bug is fixed. - Reverse geocoding Point Address results show
MatchType pointAddress, otherwise MatchType is interpolated. With gen<3 address results from reverse geocoding always show MatchType interpolated. -
gen=4 - Includes
gen=3 functionality. - Forward geocoding produces one street level result per postal code or district to avoid creating multiple results in close proximity to one another or restuls that can only be disambiguated on the basis of district name and/or postal code. With
gen<4 forward geocoding response includes multiple results per postal code or district. -
gen=5 - Includes
gen=4 functionality. - Reverse geocoding enforces the country filter. The effect is that the reverse geocoder results are constrained to the country specified in the request. This is a bug fix. With
gen<5 the reverse geocoder ignores the country filter. The behavior of the forward geocoder does not change: it has always enforced the country filter. - Reverse geocoding tries to aggregate links to a single street match instead of providing one street match per link, where only the coordinates are different.
-
LocationType (element of Location) is specific to the result and not just point for any result. LocationType is -
address: for MatchLevel houseNumber, street, intersection -
area: for MatchLevel country, state, county, city, district, postalCode - specific to the landmark for
MatchLevel landmark. E.g. park, river, golfCourse, industrialComplex, island etc. This change impacts both forward and reverse geocoder results. -
gen=6 - Includes
gen=5 functionality. - Landmarks found by the
search endpoint are exposed as Location. Before they were exposed as Place. This simplifies the response structure and removes some redundant information. See the example response for the Eiffel Tower search below. -
placeId was only derived from locationId and was never a reference to any external system -
category.categoryId is replaced by a locationType that is specific to the result since gen=5 (before locationType was always "point") -
category.categorySystemId was always "facility" -
suppliers was always empty Table 1. Landmark geocoding in gen 5 vs gen 6 search.json?
searchtext=Eiffel+Tower
&gen=5
&language=en
| search.json?
searchtext=Eiffel+Tower
&gen=6
&language=en
| relevance: 1,
matchLevel: "landmark",
matchQuality: {
name: 1
},
place: {
placeId: "801890088",
name: "Eiffel Tower",
category: [ {
categoryId: "5999",
categorySystemId: "facility"
}],
suppliers: [ {} ],
locations: [ {
locationId:
"NT_AIzytxewh0cMjfGkhX4O.B",
locationType:
"historicalMonument",
name: "Eiffel Tower",
displayPosition: {
latitude: 48.85824,
longitude: 2.2945
},
...
| relevance: 1,
matchLevel: "landmark",
matchQuality: {
name: 1
},
location: {
locationId:
"NT_AIzytxewh0cMjfGkhX4O.B",
locationType:
"historicalMonument",
name: "Eiffel Tower",
displayPosition: {
latitude: 48.85824,
longitude: 2.2945
},
...
| This change impacts forward and reverse geocoder results. - The distance for Reverse Geocoder admin area results is calculated from the supplied point to the polygon boundary. The distance is therefore negative, where the specified point is inside the area. This is aligned with landmark results. With
gen<6, the distance for admin area results is calculated from the specified point to the center of the area. -
gen=7 -
gen=8 - Includes
gen=7 functionality. -
A street match (point on link) close to the reference point is returned instead of house number match far away. This applies to reverse geocoding mode=retrieveAddresses. If a house number location is outside of the provided radius, the service does not snap to it. Instead, it returns the street level result. With gen<8, the service snaps to house number locations if the closest link position is within the provided radius and the house number location is not further away than 150 meters from that point. -
gen=9 (recommended) |
| housenumber | xs:string, exact match The house number or house name. |
| id | xs:int Item Identifier used in Multi Reverse Geocoding results to distinguish one request from another. |
| jsonattributes | xs:int If set to 1, the first character of each JSON response attribute name is set to lower case. Default value is 0. |
| jsoncallback | xs:string Specifies the name of a user-defined function used to wrap the JSON response. |
| language | LanguageCodeType The preferred language of address elements in the result. Without a preferred language, the Geocoder will return results in an official country language or in a regional primary language so that local people will understand. Language code must be provided according to RFC 4647 standard. Note that the plural form of the parameter (languages) is supported as well. But only the last specified language in the list is used. All preceding language preferences are ignored at this time. |
| level | xs:string Target match level of the search result. One of [country, state, county, city, district, postalCode]. Only valid in combination with gen=2 or higher. |
locationattributes | A comma-separated list whose elements are present in the response data. Enumeration [address, mapReference, mapView, addressDetails, streetDetails, additionalData, adminIds, linkInfo, adminInfo, timeZone, addressNamesBilingual, related.nearByAddress] Abbreviated forms: [ar, mr, mv, dt, sd, ad, ai, li, in, tz, nb, rn] The adminIds switch is available with forward geocoding only. For retrieving Time Zone information the parameter adminInfo has to be added, e.g., locationattributes=adminInfo,timeZone In reverse geocoding results, adminIds are always present unless turned off through locationattributes=none. locationattributes=-adminIds has no effect on reverse geocoding results. The related.nearByAddress switch is available with the trackPosition mode of reverse geocoding only. Default in reverse geocoding response: address, mapView, additionalData, mapReference, adminIds. Default in forward geocoding response: address, mapView, additionalData. With mapReference link PVID, side of street, and admin area PVIDs are present in the response data. With adminIds, only admin area PVIDs are present. Note: The value names are case-sensitive. |
| locationid | xs:string, exact match A key uniquely identifying a physical location. Each record in a geocode response contains a location Id. Use the Id to retrieve the exact same location information. For example, the location Id for "1 Market Street, 94105 San Francisco" is NT_NVpegjQLOBQa8ORYk3jV7A_xA. |
| mapview | See GeoBoundingBoxType Specify the map coordinates of the app's viewport. The mapview is specified by two latitude / longitude pairs; the first pair defines the top left corner of the bounding box, the second set the lower right. Matches from within the set map view plus an extended area are ranked highest. Relevant global results are also returned. mapview=<TopLeft.Latitude>,<TopLeft.Longitude>;
<BottomRight.Latitude>,<BottomRight.Longitude>
Example: mapview=41.9085286,-87.6762943;41.8682739,-87.6041965 |
| maxresults | xs:int Defines the maximum number of items in the response structure, limiting the number of results included in each response page. When more results than the defined maximum are available, then these are returned on additional, separate pages. Each response structure (page) contains a handle to the next page. For example, maxresults=5 produces a maximum of 5 results per response page. If there are eight results in total, the first page contains five results and indicates that there is a second page with further results. "metaInfo: {
timestamp: 2012-05-10T15:10:06.227+0000
nextPageInformation: 2
}"
|
| minresults | xs:int Indicates that the service is to ignore the specified radius until minResults results are found. The default is 0. Supported for Reverse Geocode mode=retrieveAreas and mode=retrieveAddresses. |
| mode | One of five values: -
retrieveAddresses - Search for the closest street address or addresses -
retrieveAreas - Retrieve the administrative area information for the position provided in the request -
retrieveLandmarks - Search for landmarks like parks and lakes in the proximity provided in the request -
retrieveAll - Search for streets, administrative areas and landmarks. This mode aggregates the results of the three different modes in one call -
trackPosition - Retrieve street and address information based on a position and bearing |
| name | xs:string Name of the landmark. The landmark name can also be provided within the searchtext. Use name instead of searchtext to avoid ambiguity for example with addresses. Highway exits also fall into the landmark category but note that those consist of a highway name and an exit name. Only the exit name should be provided in the name parameter. Below are two ways how to search for exit 4 on highway A67: search.xml?searchtext=A67&name=4search.xml?searchtext=A67+4 |
| pageinformation | xs:string A key which identifies the page to be returned when the response is separated into multiple pages. Only relevant, if maxresults has been specified in a the original request and the request response indicates that there is a further page, for example: "metaInfo: {
timestamp: 2012-05-10T15:10:06.227+0000
nextPageInformation: 2
}"
|
| politicalview | xs:string (3 bytes, ISO 3166-1-alpha-3) Specify the political view. Available territories will be seen through the point of view of this country. If this parameter is not specified the neutral international view is made available, where territories may have unresolved claims. For a complete list of supported views please see the appendix Political View. For any political view that is unsupported the Geocoder, falls back to the default view. For example, politicalview=USA or politicalview=FRA does not impact a response in any way. |
| pos | pos=lat,lon,bearing A position with latitude, longitude, and bearing. Bearing expresses the direction in which an asset is heading in degrees starting at true north and continuing clockwise around the compass. North is 0 degrees, east is 90 degrees, south is 180 degrees, west is 270 degrees. |
| postalcode | xs:string, exact match Postal code defined by the government of the country. |
| prox | GeoProximityType, see also GeoProximityType prox=lat,lon,radius A type of SpatialFilter. A spatial filter limits the search for any other attributes on the request. Proximity specifies a circle to search using a latitude, a longitude, and a radius in meters. Search is similar to mapview. Matches from inside set area are ranked higher. Relevant global results are also returned. |
| prox | GeoProximityType, see also GeoProximityType prox=lat,lon,radius A type of SpatialFilter. A spatial filter limits the search for any other attributes on the request. Proximity specifies a circle to search using a latitude, a longitude, and a radius in meters. |
| requestid | xs:string Arbitrary URL-encoded value you can use to trace request processing. If you provide a requestid, it is repeated in the MetaInfo element of the response structure. |
responseattributes | A comma-separated list whose elements are present in the response data. Enumeration [performedSearch, matchQuality, matchType, matchCode, parsedRequest] Abbreviated forms: [ps, mq, mt, mc, pr] Default in response: matchQuality, matchType Note: he value names are case-sensitive. |
| searchtext | xs:string searchtext contains free-form text containing address elements. You can specify the searchtext parameter by itself, or you can specify it with other parameters to narrow your search. For example, you can specify the state or country parameters along with a free-form address in the search text field. Note: The search text should not include non-address related elements in order to improve the relevance of results. Non-address elements in search texts can affect the quality of the results. |
| sortby | xs:string Sort results by distance (default), population count, or size (approximate area size). One of [distance, population, size]. Currently only supported for Reverse Geocode mode=retrieveAreas. If population count is not available for an entity the service falls back to sort by area size. |
| state | xs:string, exact match First subdivision level below the country. Specify state using full or abbreviated notation. A country specific mapping is required, for example - US: State
- Germany: Bundesland
|
| street | xs:string The street name can include suite, apt and floor information. When searching for a street intersection two formats are supported: |
| strictlanguagemode | xs:boolean -
True - if the value is available in the first language specified in the language parameter the attribute value is set directly in Address, Place, Location, and Category elements. Values in alternative languages are returned in the AlternativeValues element. -
False - the best available attribute value based on the language priorities given in language parameter is returned directly in Address, Place, Location, and Category elements. No alternatives are returned. |
| token | xs:string An URL-encoded Base64 string of typically (but not guaranteed to be) 24 bytes. The token is generated based on the user's app_id and received after the registration process of the application. Parameter token is deprecated, use app_code instead. |
