HERE Geocoder API
In maintenance
Migrate to HERE Geocoding & Search API 7
Geocoder API Developer's Guide

Backwards Compatibility

All minor API updates and bug fixes are implemented to preserve compatibility with existing applications. Major updates that significantly change the API behavior are released on a different URL.

Backwards Compatible Changes

The following request interface changes are considered backward compatible:

  • Adding new endpoints
  • Adding new optional parameters
  • Adding new enumeration values
  • Changing a parameter from mandatory to optional
  • Softening a parameter constraint

The following changes in response structures are considered backward compatible:

  • Adding new optional elements
  • Adding new enumeration values
  • Switching from mandatory to optional for an element but still ensuring that the element will be populated for existing requests
  • Adding new error subtypes
  • Hardening constraint for an element value

Note that adding new endpoints or optional parameters is not backwards compatible according to the classic definition of backwards compatibility, which states that the response from a more recent version of the API should still be valid according to the XML schema of an older version. For these reasons, applications should be able to handle unknown elements and enumeration values when parsing a response.

Different Generations of the Same API

Evolutions of the API that result in backwards incompatible changes to the response data are tagged using a monotonically increasing generation number. A higher generation number includes all previous generations unless functionality is overridden by the latest generation.

If your application requires response output produced by an earlier generation of the Geocoder API, include the appropriate generation number in the request by including the request parameter gen.

Examples of backwards incompatible changes that you can bypass using the gen parameter are:

  • A change to the semantics of a filter, for example from a strict to a weak filter
  • A change to the number of results in the response, for example, by introducing a fallback strategy to provide results even if the request cannot be fulfilled completely
  • A change in the order of the results

The response changes corresponding to specific generation numbers are described below.

Supported Generation Numbers

The list below documents the supported generation number values and summarizes the corresponding functionality.

To see how generation numbers are used in requests, refer to Examples and try sending Geocoder API requests.

  • 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 showMatchType 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
    • Includes gen=6 functionality.
    • The radius value for Reverse Geocoder mode=retrieveAreas requests is no longer ignored. If the proximity value is provided and greater than 0, then areas that lie within the radius are contained in the response. Example: Request area information for a coordinate in Potsdam, a city near Berlin:

      mode=retrieveAreas&prox=52.39702,13.04811,10000&level=city&gen=7.

      In addition to results for Potsdam, the response contains results for Berlin and other nearby towns that lie within 10,000 meters from the specified location.
  • 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)
    • Includes gen=8 functionality.

    • Location.AdminInfo.TimeZoneOffset has been moved to Location.AdminInfo.TimeZone.Offset together with the other time zone information. See Timezone for details.

      Table 2. Time zone offset changes gen 9 vs gen 8 
      &gen=8
&locationattributes=tz
      		 
      &gen=9
&locationattributes=tz
      		 
      Location.AdminInfo.TimeZoneOffset
Location.AdminInfo.LocalTime
Location.AdminInfo.Currency
Location.AdminInfo.DrivingSide
Location.AdminInfo.SystemOfMeasure
      		 
      Location.AdminInfo.LocalTime
Location.AdminInfo.Currency
Location.AdminInfo.DrivingSide
Location.AdminInfo.SystemOfMeasure
Location.AdminInfo.TimeZone.Id
Location.AdminInfo.TimeZone.Offset
Location.AdminInfo.TimeZone.RawOffset
Location.AdminInfo.TimeZone.NameShort
Location.AdminInfo.TimeZone.NameLong
Location.AdminInfo.TimeZone.NameDstShort
Location.AdminInfo.TimeZone.NameDstLong
Location.AdminInfo.TimeZone.InDaylightTime
Location.AdminInfo.TimeZone.DstSavings

Note that the changes shown above are not the only changes introduced between any two generations of the API. Only changes that might cause conflicts with existing client implementations are tagged with a specific generation number.

Developer

Products
Community
Company
Privacy Settings Privacy Policy Cookie Policy Service Terms

© 2023 HERE