Geocoder API Developer's Guide

Reverse Geocoding Examples

This section provides examples of reverse geocoding requests.

Find Addresses Near a Position

The mode parameter specifies that the service should snap to closest address or street. In this request the radius is limited to 100 meters. If no address or street is found within that radius the service falls back to retrieval of area information. The gen parameter with value >=1 is essential for limiting the results to locations within the set radius. See also Generation History

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml
?prox=50.112,8.683,100
&mode=retrieveAddresses
&app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&gen=9

Retrieve Area Information at a Position

Example request to retrieve area information at the set position. The mode parameter is set to retrieveAreas which instructs the service to retrieve the area information at the set position.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml
?prox=50.112,8.683
&mode=retrieveAreas
&app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&gen=9

Retrieve Nearby Area Information around a Position

Example request to retrieve area information nearby the set position. The mode parameter is set to retrieveAreas. The radius of the prox parameter is set to 10,000. level limits results to match level city. By default any admin level is returned. sortby instructs the service to sort the results by population count. Results can also be sorted by size (approximate area size) and by distance (default). Retrieval of nearby area information requires gen=7 or higher. With gen<7 the function falls back to retrieval of the area information at the specified position only.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml
?prox=50.112,8.683,10000
&mode=retrieveAreas
&level=city
&sortby=population
&app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&gen=9

Retrieve Area and Landmark Information at a Position

The example below retrieves area and landmark information from a point close to the Presido in San Francisco. The mode parameter is set to retrieveAll. No radius is provided because we just want to know what is at that point. For example, we are not interested in streets or addresses near-by.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml
?prox=37.80358,-122.44832
&mode=retrieveAll
&app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&gen=9
Two areas are intersecting with the given point: The landmark "Palace of Fine Arts" and the district "Presidio". Below are details for both results. The complete admin and address information is also part of the results. The information is just omitted below for space reasons. The distance is negative for both results because the given point is inside the polygon.
Note: Since gen=6 the distance for admin area results is calculated from the given point to the polygon boundary. This allows client applications to tell whether the given point is inside the polygon or not. With gen<6 the distance is calculated from the given point to the area centroid.
distance: -117.2
direction: 254.5
matchLevel:  "district",
...
location: {
    locationId:  "NT_3k-9bTamuJdmfGCuY9h3wB",
    locationType:  "area",
    ...
    address: {
     label: "Presidio, San Francisco, CA, United States",
    ...

distance: -73.7
matchLevel:  "landmark",
...
location: {
    locationId:  "NT_uQxRsUDYq4Gf3gjb2bKrEB_p_wcyTPTwD08nAzfdHIKshSB",
    locationType:  "park",
    name:  "Palace of Fine Arts",
    ...
    address: {
     label: "Palace Dr, San Francisco, CA 94123, United States",
    ...

Retrieve Landmarks Around a Position

This example looks at landmarks in the proximity of Sand Hill Rd in Palo Alto. For this example we are not interested in admin information and also not in streets or addresses. The mode parameter is set to retrieveLandmarks and the radius is set to 1000 meters.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml
?prox=37.43823,-122.17796,1000
&mode=retrieveLandmarks
&app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&gen=9

There are five landmarks found within this proximity including a shopping center, a university, a hospital and two parks. The matchLevel for all is "landmark". Here are details from the first result:

distance:  171.7
matchLevel:  "landmark",
...
location: {
    locationId: "NT_5WFfaH0.F5ZFwve3Ns3w3A_p_mafrT7LahvODUZjOMtdtaC",
    locationType: "hospital",
    name: "Stanford Hospital & Clinics",
    ...
    address: {
     label: "300 Pasteur Dr, Stanford, CA 94305, United States",
    ...

Retrieve Address Information at a Position using Search

A simple way to make reverse geocoding requests is to pass the coordinates as searchtext to the search endpoint.

The following coordinate formats are supported, where D= degree, M= minute and S= second.

  • DD.MMMMM
  • DD.MMMMM°
  • DD MM SS
  • DD MM SS.SS
  • DD°MM'SS"
  • DD°MM'SS.SS"
  • DD°MM.SS'

Each with +/- pre- and N/S/E/W post-fixes. Spaces are ignored. If latitude (first) coordinate is less than -90 or greater than 90 then latitude and longitudes are switched. Examples:

  • 37,121
  • 37, 121
  • 121.0 37.0
  • 37N, 121W
  • 37N,121W
  • 37N 121W
  • 37N, -121W (Latitude 37 Longitude 121: negative West equals East: a location in China)
  • 37° 121°
  • 37°0'0" 121°0'0"
  • 50° 9' 43" N 8° 32' 1" E

Invalid formats due to potential conflicts with postal codes.

  • 37 121
  • 121 37

An example using searchtext containing coordinates.

https://geocoder.cit.api.here.com/6.2/search.xml
?searchtext=50.1115118%208.6805059
&app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&gen=9

Track Position Using Bearing Information

Client applications can track vehicle positions more accurately by providing the travel direction in form of bearing information to the Reverse Geocoder. Without the bearing, the Reverse Geocoder might falsely snap to a crossing street, to an over- or underpass, or to a nearby street - if it is closer to the provided coordinate. This can happen easily because of the inaccuracy of the GPS.

Use mode=trackPosition and pos with coordinate and bearing for this use case. In the example below a client application passes on a position near the intersection of O'Farrell St (going east) and Van Ness Ave (going north) in San Francisco. In this case, the position is on Van Ness and a few meters north of O'Farrell. The bearing is 80 degrees. This means the vehicle most likely travels east and then O'Farrell is the better match. Without bearing information or with mode=retrieveAddresses the first result would be on Van Ness Ave, which is most likely not the street that the vehicle is on.

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml
?pos=37.7849507,-122.4211569,80
&mode=trackPosition
&app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&gen=9

The results are sorted by Relevance, which for mode=trackPosition expresses the confidence of the Reverse Geocoder into this match. The first three results are shown below. The third result Van Ness Ave is only 0.3 meters away from the provided position. But because of the bearing the confidence is lower than for the other two matches.

relevance: 0.78
distance:  21.5
matchLevel:  "street",
...
location: {
    locationId: "NT_nr8HVxV.kOEiHXKlHoIE0A_l_815826134_L",
    locationType: "address",
    ...
    address: {
     label: "O'Farrell St, San Francisco, CA 94109, United States",
    ...

relevance: 0.68
distance:  31.6
matchLevel:  "street",
...
location: {
    locationId: "NT_5V25cCF0wAAoQ4CqmCMt8C_l_815826136_R",
    locationType: "address",
    ...
    address: {
     label: "Myrtle St, San Francisco, CA 94109, United States",
    ...

relevance: 0.62
distance:  0.3
matchLevel:  "street",
...
location: {
    locationId: "NT_5DmLoeLNDKXxFIbZ44QhfA_l_815826149_L",
    locationType: "address",
    ...
    address: {
     label: "Van Ness Ave, San Francisco, CA 94109, United States",
    ...

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.