Migrate Geocoding and Landmark Geocoding Requests

This section covers the actions that must be taken to migrate a HERE Geocoder API Geocoding request to a GS7 Geocode request and a GS7 Lookup By ID request.

HERE Geocoder API Landmark Geocoding: not supported. For landmark queries use /discover. If you use Landmark Geocoding for address search, use /geocode.

For more details about the types or specification of parameters, see the Developer Guide.

Base URL, Version, Resource

Use the GS7 /geocode endpoint to migrate the freeform or qualified search text queries to GS7.

Parameter HERE Geocoder API GS7
Base URL https://geocoder.api.here.com https://geocode.search.hereapi.com
Version /6.2 /v1
Resource / Endpoint /geocode /geocode
/search /geocode
Format specifier .xml -
.json -

Use the GS7 /discover endpoint to migrate the landmark queries to GS7.

Parameter HERE Geocoder API GS7
Base URL https://geocoder.api.here.com https://discover.search.hereapi.com
Version /6.2 /v1
Resource / Endpoint /search /discover
Format specifier .xml -
.json -

Use the GS7 /lookup endpoint to look up entities by ID.

Parameter HERE Geocoder API GS7
Base URL https://geocoder.api.here.com https://lookup.search.hereapi.com
Version /6.2 /v1
Resource / Endpoint /geocode /lookup
Format specifier .xml -
.json -

HERE Geocoder API supports XML and JSON output formats. HERE Geocoding and Search v7 supports JSON output format only. The format specifier is therefore not required and must be omitted.

Query parameters

HERE Geocoder API GS7 comment
additionaldata=Country2 show=countryInfo
additionaldata=PreserveUnitDesignators show=parsing GS7 /geocode includes secondary unit designators in the parsing information. The parsing feature of GS7 /geocode is in BETA state.
city qq=city Example: qq=city:Berlin
country in=countryCode GS7 supports ISO 3166-1 alpha-3 country codes, and requires all upper-cased letters. Example: in=countryCode:DEU,AUT
countryfocus qq=country Qualified country field of GS7 /geocode supports spelled-out country names as well as ISO 3166-1 alpha-3 country codes. This parameter is not considered as a filter, but as a part of structured query. The results with matching country names are ranked higher.
county qq=county
district qq=district
housenumber qq=houseNumber GS7 /geocode recognizes building name as part of the query. But it does not allow to search for an address based on building name only. The query shall contain other detailed address information, such as house number in conjunction with street name or, in case of IRL and SGP, detailed postal code.
language lang List of languages is not supported.
locationattributes.streetDetails (sd) show=streetInfo
maxresult limit GS7 limit parameter limits the total number of results. GS7 does not have the concept of multiple response pages.
politicalview politicalview GS7 politicalview parameter accepts all uppercase single ISO 3166-1 alpha-3 country codes. The complete list of currently supported political views can be found at Supported Political Views. 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.
postalcode qq=postalCode
prox at GS7 at parameter does not support radius.
responseattributes.parsedRequest (pr) show=parsing The parsing feature of GS7 /geocode is in BETA state.
searchText q
state qq=state
street qq=street Similar to HERE Geocoder API the GS7 /geocode supports in the qualified street field: single street input, address line or street intersection input. The address line input additionally to the street name includes the house number and may include the suite, apt and floor information. The street intersection input includes two or more street names concatenated using one of the predefined separators (global: "&", "@", "and", "at"; additionally for queries with street names in Spanish or Portuguese languages: "esq", "esquina", "por", "con", "y"). In many cases the Geocoder can also detect as intersection street names when they are separated by a comma or space.
locationattributes.timeZone (tz) show=tz

Response attributes

HERE Geocoder API GS7 comment
View.Result[].Relevance items[].scoring.queryScore Same semantic as in HERE Geocoder API but changes in the calculation logic can lead to slightly different values.
View.Result[].Distance items[].distance
View.Result[].MatchLevel items[].resultType extended with one of: items[].addressBlockType, items[].localityType, items[].administrativeAreaType For details, see result types. Note, that GS7 /geocode also returns place results.
View.Result[].MatchQuality items[].scoring.fieldScore Same semantic as in HERE Geocoder API but changes in the calculation logic can lead to slightly different values.
View.Result[].MatchType items[].houseNumberType For details, see result types.
View.Result[].ParsedRequest items[].parsing The representation has changed. For more details, see the API Reference. The parsing feature of GS7 /geocode is in BETA state.
View.Result[].Location.LocationId items[].id The location id of HERE Geocoder API and id of GS7 have different formats and are not compatible.
View.Result[].Location.LocationType items.categories[] Location types: area and address are removed as redundant. Location type distanceMarker is not supported. Other location types are covered by place category information. For more details, see the Places Category system.
View.Result[].Location.Name items[].title GS7 field title contains the localized display name for result item. For place type results, the field shows the the place name. For address type results, the field shows the localized form of the address. The result title format may differ from the one used by the HERE Geocoder API. In particular no double quotes are used for building names.
View.Result[].Location. DisplayPosition.Latitude items[].address.position.lat
View.Result[].Location. DisplayPosition.Longitude items[].address.position.lng
View.Result[].Location. NavigationPosition.Latitude items[].address.access.lat GS7 returns an access position only if the result has an access point that is different from the position point. In HERE Geocoder API results the navigation position is simply a duplicate of the display position in cases where the data does not provide a true navigation position.
View.Result[].Location. NavigationPosition.Longitude items[].address.access.lng
View.Result[].Location.MapView items[].mapView The data format has changed. For more details, see the API Reference. Note that place results do not have map view.
View.Result[].Location. Address.Label items[].address.label The address label format may differ from the one used by the HERE Geocoder API. In particular no double quotes are used for building names.
View.Result[].Location. Address.Country items[].address.countryCode GS7 returns country name in the countryName field and country code in countryCode field.
View.Result[].Location. Address.State items[].address.state, items[].address.stateCode GS7 returns state name in the state field and state code, where commonly used, in stateCode field.
View.Result[].Location. Address.County items[].address.county, items[].address.countyCode GS7 returns county name in the county field and county code, where commonly used, in countyCode field.
View.Result[].Location. Address.City items[].address.city
View.Result[].Location. Address.District items[].address.district
View.Result[].Location. Address.Subdistrict items[].address.subdistrict
View.Result[].Location. Address.Street items[].address.street, items[].address.streets For house number or street results, GS7 returns the single street name in the field street. For intersection results, GS7 returns a list of street names in the array streets (plural).
View.Result[].Location. Address.HouseNumber items[].address.houseNumber
View.Result[].Location. Address.PostalCode items[].address.postalCode
View.Result[].Location. Address.Building items[].address.building
View.Result[].Location.Address .AdditionalData[Country2] items[].countryInfo.alpha2
View.Result[].Location.Address .AdditionalData[CountryName] items[].address.countryName GS7 returns country name in the countryName field and country code in countryCode field.
View.Result[].Location.Address .AdditionalData[StateName] items[].address.state GS7 returns state name in the state field and state code, where commonly used, in stateCode field.
View.Result[].Location.Address .AdditionalData[CountyName] items[].address.county GS7 returns county name in the county field and county code, where commonly used, in countyCode field.
View.Result[].Location.Address .AdditionalData[<secondary address units>] items[].parsing.secondaryUnits GS7 /geocode includes the detected secondary unit designators in the parsing block. The parsing feature of GS7 /geocode is in BETA state.
View.Result[].Location. AddressDetails.StreetDetails items[].streetInfo
View.Result[].AdditionalData [houseNumberFallback] items[].houseNumberFallback
gen=9: View.Result[].adminInfo.timeZone, gen<9: View.Result[].adminInfo.timeZoneOffset items[].timeZone The representation has changed. For more details, see the API Reference. If more timezone-specific details, other than the timezone's name and UTC offset, are needed, they can be derived from the timezone's name and the help of a library suited for the client's software stack.

Currently not supported

The following query parameters are currently not supported in GS7 Geocode service:

HERE Geocoder API comment
additionaldata=AdditionalAddressProvider
additionaldata=AddressRangeSqueezeFactor
additionaldata=AddressRangeSqueezeOffset
additionaldata=CrossingStreets
additionaldata=FlexibleAdminValues GS7 /geocode by default supports flexible admin values with penalty on the query score.
additionaldata=HouseNumberMode GS7 /geocode always works in house number fallback mode: fallback to the next closest house number is performed within a predefined maximum house number distance.
additionaldata=IncludeChildPOIs
additionaldata=IncludeDistanceMarkers N/A
additionaldata=IncludeMicroPointAddresses
additionaldata=IncludeRoutingInformation
additionaldata=IncludeShapeLevel
additionaldata=IncludeZipAddOn GS7 /geocode always adds the USA ZIP+4 postal code extension where available and applicable to the ZIP code.
additionaldata=IntersectionSnapTolerance N/A
additionaldata=NormalizeNames
additionaldata=RestrictLevel N/A
additionaldata=SuppressStreetType N/A
addressattributes GS7 /geocode has fixed set of the address attributes. Included: country, state, county, city, district, subdistrict, street, houseNumber, postalCode; country, state and county names from additionalData. Not included: addressLines; other elements of additionalData.
app_code GS7 authentication does not support the app_id/app_code method. For the available authentication options, see the Identity & Access Management Developer Guide.
app_id GS7 authentication does not support the app_id/app_code method. For the available authentication options, see the Identity & Access Management Developer Guide.
bbox GS7 /geocode does not support spatial filters. Use the at parameter for spatial reference.
categoryids GS7 /geocode does not support filtering by category id.
gen
jsonattributes
jsoncallback
locationattributes.address (ar) GS7 /geocode results always contain address information.
locationattributes.mapReference (mr) GS7 /geocode does not support map reference information.
locationattributes.mapView (mv) GS7 /geocode results always contain mapview information, except for place results.
locationattributes.addressDetails (dt) GS7 /geocode does not support address details information.
locationattributes.additionalData (ad) GS7 /geocode does not support location additional data (ExtendedTopLeftLatitude, ExtendedTopLeftLongitude, ExtendedBottomRightLatitude, ExtendedBottomRightLongitude, additionalAddressProvider).
locationattributes.adminIds (ai) GS7 /geocode does not provide administrative IDs in results.
locationattributes.linkInfo (li) GS7 /geocode does not provide link information in results.
locationattributes.adminInfo (in) GS7 /geocode does not provide any additional administrative information in results.
locationattributes.addressNamesBilingual (nb) GS7 /geocode does not provide bilingual address names in results.
locationattributes.related.nearByAddress (rn) GS7 /geocode does not provide nearby locations in results.
locationattributes.all
locationattributes.none
locationid Use GS7 /lookup endpoint to retrieve the results through their ID. The location id of HERE Geocoder API and id of GS7 have different format and are not compatible.
mapview GS7 /geocode does not support spatial filters. Use the at parameter for spatial reference.
name GS7 /geocode does not support place name as a subparameter of qualified query. The landmark name can be provided within the freeform search text in q parameter.
pageinformation GS7 does not have the concept of multiple response pages. The limit parameter limits the total number of the results.
responseattributes.performedSearch (ps) GS7 /geocode has fixed set of the response attributes. Performed search information is not supported.
responseattributes.matchQuality (mq) GS7 /geocode has fixed set of the response attributes. Match quality values are included in fieldScore.
responseattributes.matchType (mt) GS7 /geocode has fixed set of the response attributes. Match type is included in houseNumberType.
responseattributes.matchCode (mc) GS7 /geocode has fixed set of the response attributes. Match code is not supported.
responseattributes.all GS7 /geocode has fixed set of the response attributes.
responseattributes.none GS7 /geocode has fixed set of the response attributes.
street0 GS7 /geocode supports street intersection input as freeform text. Alternatively, all the intersecting streets may be specified within the single qualified field street. GS7 /geocode does not support street intersection input in multiple street fields.
street1 GS7 /geocode does not support street intersection input in multiple street fields.
strictlanguagemode
token For more information, see the Identity & Access Management Developer Guide.

The following response attributes are currently not returned by GS7 Geocode service:

HERE Geocoder API comment
MetaInfo GS7 response does not include metainfo (RequestId, Timestamp, NextPageInformation, PreviousPageInformation, request AdditionalData).
View GS7 response does not have this additional level above the result items list.
View.PerformedSearch
View.Result[].Direction
View.Result[].MatchCode
View.Result[].Location.Shape
View.Result[].Location. Address.DistanceMarker GS7 /geocode does not support distance markers.
View.Result[].Location. Address. AddressLine
View.Result[].Location.Address .AdditionalData[CrossingStreet0]
View.Result[].Location.Address .AdditionalData[CrossingStreet1]
View.Result[].Location.Address .AdditionalData[PostalCodeType]
View.Result[].Location. AddressDetails.CountryCode GS7 /geocode does not support address details information.
View.Result[].Location. AddressDetails.Country GS7 /geocode does not support address details information.
View.Result[].Location. AddressDetails.State GS7 /geocode does not support address details information.
View.Result[].Location. AddressDetails.County GS7 /geocode does not support address details information.
View.Result[].Location. AddressDetails.City GS7 /geocode does not support address details information.
View.Result[].Location. AddressDetails.District GS7 /geocode does not support address details information.
View.Result[].Location. AddressDetails.Street GS7 /geocode does not support address details information.
View.Result[].Location. AddressDetails.HouseNumber GS7 /geocode does not support address details information.
View.Result[].Location. AddressDetails.PostalCode GS7 /geocode does not support address details information.
View.Result[].Location. AddressDetails.Building GS7 /geocode does not support address details information.
View.Result[].Location. AddressNames GS7 /geocode does not return additional address names.
View.Result[].Location.MapReference GS7 /geocode does not return map reference.
View.Result[].Location.LinkInfo GS7 /geocode does not include link information into the response.
View.Result[].Location.AdminInfo GS7 /geocode does not include admin information into the response.
View.Result[].Location.Related GS7 /geocode does not support related locations.
View.Result[].Location. AdditionalData GS7 /geocode does not support location additional data (ExtendedTopLeftLatitude, ExtendedTopLeftLongitude, ExtendedBottomRightLatitude, ExtendedBottomRightLongitude, additionalAddressProvider).
View.Result[].Place GS7 /geocode also returns place results. For details, see result types.
View.Result[].AdditionalData [houseNumberFallbackDifference] Removed as redundant. Difference between the requested house number and the matched house number can be derived from items[].scoring.fieldScore.houseNumber.
View.Result[].AdditionalData [houseNumberExtrapolation] Removed. GS7 /geocode does not support house number extrapolation mode.
View.Result[].AdditionalData [houseNumberExtrapolationDistance] Removed. GS7 /geocode does not support house number extrapolation mode.
View.Result[].AdditionalData [houseNumberExtrapolationDifference] Removed. GS7 /geocode does not support house number extrapolation mode.

results matching ""

    No results matching ""