Geocoder API Developer's Guide

Using Backwards Incompatible Features

All minor API updates and bugfixes are implemented in a way that does not break compatibility with existing applications. Major updates that significantly change the API behavior are released on a different URL.

Backwards Compatibility

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.

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 while parsing a response.

Different Generations of the Same API

To enable backwards incompatible functionality within the same major version of an API without impacting existing applications use the gen parameter. Examples of these kinds of changes are:

  • Changing the semantics of a filter criteria from a strict to a weak filter
  • Changing 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
  • Changing the order of results

Evolutions of the API functionality are tagged using a monotonically increasing generation number. A higher generation number includes all previous generations unless functionality is overridden by the latest generation.

Any changes to functionality that need a particular generation number are labeled in the documentation.

If you do not specify the generation parameter no backwards incompatible functionality is enabled. Specifying the generation parameter allows the software to consider the application implementation assumptions.

Generation History

These are the supported generations together with the functionality that is available using only the corresponding generation parameter value.

  • gen=0 default behavior
  • gen=1
    • If a reverse geocoding request for an address does not find an address or street within the set 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.
    • Return the area display point (e.g. the center of the area) for reverse geocode area responses. With gen<2 the DisplayPoint simply mirrors the point from the request.
    • Return map version in element MapReference if requested via locationattributes=(one of mr, mapReference, all)
  • gen=3
    • Includes gen=2 functionality.
    • Reverse geocoding address results have display and navigation positions. With gen<3 address results from reverse geocoding only have a display position which in actuality is the navigation position. With gen=3 this bug is fixed.
    • MatchType pointAddress for reverse geocoding Point Address results. Otherwise interpolated. With gen<3 address results from reverse geocoding always have MatchType interpolated.
  • gen=4
    • Includes gen=3 functionality.
    • Forward geocoding: Avoid ambiguous street level results that are near to each other and/or can only be disambiguated based on one or a combination of district name/postal code. With gen<4 forward geocoding responses have one result per postal code or district.
  • gen=5
    • Includes gen=4 functionality.
    • Reverse geocoding: Enforce country filter. Reverse geocoder results are constrained to the set country. This is a bug fix. With gen<5 reverse geocoder ignores the country filter. Forward geocoder behavior does not change. The country filter has always been enforced.
    • Reverse geocoding: Reverse Geocoder tries to aggregate links to a single street match instead providing one street match per link where only 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 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 example response for 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
        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 given point to the polygon boundary. The distance is therefore negative in cases where the given point is inside the area. This is now aligned with landmark results. With gen<6 the distance for admin area results is calculated from the given 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 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.

      Besides Potsdam the response contains results Berlin and other nearby cities that lie within 10,000 meters from the given coordinate.
  • gen=8
    • Includes gen=7 functionality.
    • Prefer street match (point on link) close to reference point 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 do not snap to it. Instead, return 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 from that point.

  • gen=9 (recommended)
    • Includes gen=8 functionality.
    • Location.AdminInfo.TimeZoneOffset moved to Location.AdminInfo.TimeZone.Offset together with the other time zone information. See Timezone for details.

      &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

Please note that the previous list of changes are not the only changes introduced between two generations. Only changes that might cause conflicts with existing client implementations are tagged with a specific generation number.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.