Geocoder API Developer's Guide

Reverse Geocode Request

The reversegeocode endpoint allows client applications to either retrieve street address information corresponding to a given coordinate and radius or to retrieve area information for a given coordinate.

Retrieve Addresses

The following example is a request for addresses (mode=retrieveAddresses) within 100 meters of latitude 50.111 and longitude 8.680.

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

The results are sorted by distance from the search center. Each result in the response contains the following information:

  • Relevance is always 1.0 for reverse geocode retrieveAddresses results.
  • Distance in meters from the search center.
  • MatchLevel shows the level of the most precise area information for the match.
  • MatchQuality is always 1.0 for reverse geocode results.
  • Location information:

    • LocationType which is one of point, area or line.
    • Latitude and longitude of the address.
    • Latitude and longitude of the area to display the address on a map (MapView).
    • Actual street address of the location.
    • MapReference, containing the unique id of the location.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:Search xmlns:ns2="http://www.navteq.com/lbsp/Search-Search/4">
  <Response>
    <MetaInfo>
      <Timestamp>2015-09-15T06:34:14.645Z</Timestamp>
      <NextPageInformation>2</NextPageInformation>
    </MetaInfo>
    <View xsi:type="ns2:SearchResultsViewType">
      <ViewId>0</ViewId>
      <Result>
        <Relevance>1.0</Relevance>
        <Distance>0.7</Distance>
        <MatchLevel>houseNumber</MatchLevel>
        <MatchQuality>
          <Country>1.0</Country>
          <State>1.0</State>
          <County>1.0</County>
          <City>1.0</City>
          <District>1.0</District>
          <Street>1.0</Street>
          <HouseNumber>1.0</HouseNumber>
          <PostalCode>1.0</PostalCode>
        </MatchQuality>
        <MatchType>pointAddress</MatchType>
        <Location>
          <LocationId>NT_OV3A4F7PVZMW36XQixpFiB_zAD</LocationId>
          <LocationType>address</LocationType>
          <DisplayPosition>
            <Latitude>50.1123</Latitude>
            <Longitude>8.68285</Longitude>
          </DisplayPosition>
          <NavigationPosition>
            <Latitude>50.112</Latitude>
            <Longitude>8.68301</Longitude>
          </NavigationPosition>
          <MapView>
            <TopLeft>
              <Latitude>50.1134242</Latitude>
              <Longitude>8.681097</Longitude>
            </TopLeft>
            <BottomRight>
              <Latitude>50.1111758</Latitude>
              <Longitude>8.684603</Longitude>
            </BottomRight>
          </MapView>
          <Address>
            <Label>Berliner Straße 30, 60311 Frankfurt am Main, Deutschland</Label>
            <Country>DEU</Country>
            <State>Hessen</State>
            <County>Frankfurt am Main</County>
            <City>Frankfurt am Main</City>
            <District>Altstadt</District>
            <Street>Berliner Straße</Street>
            <HouseNumber>30</HouseNumber>
            <PostalCode>60311</PostalCode>
            <AdditionalData key="CountryName">Deutschland</AdditionalData>
            <AdditionalData key="StateName">Hessen</AdditionalData>
            <AdditionalData key="CountyName">Frankfurt am Main</AdditionalData>
          </Address>
          <MapReference>
            <ReferenceId>52308768</ReferenceId>
            <MapId>UWAM15124</MapId>
            <MapVersion>Q1/2015</MapVersion>
            <Spot>0.86</Spot>
            <SideOfStreet>left</SideOfStreet>
            <CountryId>20147700</CountryId>
            <StateId>20160993</StateId>
            <CountyId>20161002</CountyId>
            <CityId>20161003</CityId>
            <DistrictId>20299860</DistrictId>
            <AddressId>168611036</AddressId>
          </MapReference>
        </Location>
      </Result>
    </View>
  </Response>
</ns2:Search>

Retrieve Areas Information

The second example is a request for information (mode=retrieveAreas) about the area at the point 50.111, 8.680. The radius is optional. With gen<7 the radius is ignored. With gen=7 or higher the radius is not ignored and areas whose polygon boundaries lie within the radius are returned as well. The mode can then be used to retrieve nearby areas.

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

The response includes

  • Relevance is always 1.0 for reverse geocode retrieveAreas results.
  • Distance from the specified client position to the edge of the location area.
  • Direction of the location seen from the specified client position.
  • MatchLevel shows the level of the most precise area information available for the match, district, city or a higher administrative level.
  • Location information in terms of:

    • LocationType which is one of point, area or line.
    • Latitude and longitude of the area.
    • Latitude and longitude of the area to display the area on a map (MapView).
    • Address (only the area information, no street or house number).
  • MapReference information with Map version and IDs

<Result>
  <Relevance>1.0</Relevance>
  <Distance>-208.7</Distance>
  <Direction>165.2</Direction>
  <MatchLevel>district</MatchLevel>
  <MatchQuality>
    <Country>1.0</Country>
    <State>1.0</State>
    <County>1.0</County>
    <City>1.0</City>
    <District>1.0</District>
    <PostalCode>1.0</PostalCode>
  </MatchQuality>
  <Location>
    <LocationId>NT_xG5rpFd6qDwqrPmW-sF-QA</LocationId>
    <LocationType>area</LocationType>
    <DisplayPosition>
      <Latitude>50.11132</Latitude>
      <Longitude>8.68328</Longitude>
    </DisplayPosition>
    <MapView>
      <TopLeft>
        <Latitude>50.11482</Latitude>
        <Longitude>8.67477</Longitude>
      </TopLeft>
      <BottomRight>
        <Latitude>50.10693</Latitude>
        <Longitude>8.68821</Longitude>
      </BottomRight>
    </MapView>
    <Address>
      <Label>
        Altstadt, Frankfurt am Main, Hessen, Deutschland
      </Label>
      <Country>DEU</Country>
      <State>Hessen</State>
      <County>Frankfurt am Main</County>
      <City>Frankfurt am Main</City>
      <District>Altstadt</District>
      <PostalCode>60311</PostalCode>
      <AdditionalData key="CountryName">Deutschland</AdditionalData>
      <AdditionalData key="StateName">Hessen</AdditionalData>
      <AdditionalData key="CountyName">Frankfurt am Main</AdditionalData>
    </Address>
    <MapReference>
      <ReferenceId>755686533</ReferenceId>
      <MapId>UWAM15124</MapId>
      <MapVersion>Q1/2015</MapVersion>
      <SideOfStreet>neither</SideOfStreet>
      <CountryId>20147700</CountryId>
      <StateId>20160993</StateId>
      <CountyId>20161002</CountyId>
      <CityId>20161003</CityId>
      <DistrictId>20299860</DistrictId>
    </MapReference>
  </Location>
</Result>

Track Position

Client applications can track vehicle positions more accurately by providing bearing information to the Reverse Geocoder. Without any additional information the Reverse Geocoder might falsely snap to a crossing street, to an over- or underpass, or to a nearby street - whatever is closer to the provided coordinate. The example below tracks the position mode=trackPosition by providing the bearing together with the position in the pos parameter. Bearing expresses the direction in which the vehicle 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. The position in the example is close to an intersection (Königsteiner Straße and Allee Strasse in Bad Soden, Germany). In the request a north heading (350 degrees) is provided.

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

The first result is Königsteiner Straße (1 in the left image) even though Allee Strasse (2) is closer to the given position. The arrow in the image shows the bearing. The result flips around when changing to an east heading (30 degrees). The first result is then Allee Strasse (right image).

reversegeocode.xml
?mode=trackPosition
&pos=50.1417995,8.5034505,350
reversegeocode.xml
?mode=trackPosition
&pos=50.1417995,8.5034505,30

The response includes

  • Relevance expressing the confidence in the match. Values between 0 an 1.0.
  • Distance from the specified position to the link match.
  • MatchLevel always street for trackPosition results.
  • Location information in terms of:

    • LocationType is always address for gen=5 and higher, point otherwise.
    • Latitude and longitude of the address.
    • Latitude and longitude of the area to display the address on a map (MapView).
    • Address (only the area information, no street or house number).
  • MapReference information with Map version and IDs

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:Search xmlns:ns2="http://www.navteq.com/lbsp/Search-Search/4">
  <Response>
    <MetaInfo>
      <Timestamp>2015-09-15T06:34:14.645Z</Timestamp>
    </MetaInfo>
    <View xsi:type="ns2:SearchResultsViewType">
      <ViewId>0</ViewId>
      <Result>
        <Relevance>0.68</Relevance>
        <Distance>20.2</Distance>
        <MatchLevel>street</MatchLevel>
        <MatchQuality>
          <Country>1.0</Country>
          <State>1.0</State>
          <County>1.0</County>
          <City>1.0</City>
          <Street>1.0</Street>
          <PostalCode>1.0</PostalCode>
        </MatchQuality>
        <Location>
          <LocationId>NT_VTZCRAxyPhgdwOX01.5y8A_l_52361527_L</LocationId>
          <LocationType>address</LocationType>
          <DisplayPosition>
            <Latitude>50.1419495</Latitude>
            <Longitude>8.5036109</Longitude>
          </DisplayPosition>
          <MapView>
            <TopLeft>
              <Latitude>50.14287</Latitude>
              <Longitude>8.50275</Longitude>
            </TopLeft>
            <BottomRight>
              <Latitude>50.14136</Latitude>
              <Longitude>8.50419</Longitude>
            </BottomRight>
          </MapView>
          <Address>
            <Label>Königsteiner Straße, 65812 Bad Soden am Taunus, Deutschland</Label>
            <Country>DEU</Country>
            <State>Hessen</State>
            <County>Main-Taunus-Kreis</County>
            <City>Bad Soden am Taunus</City>
            <Street>Königsteiner Straße</Street>
            <PostalCode>65812</PostalCode>
            <AdditionalData key="CountryName">Deutschland</AdditionalData>
            <AdditionalData key="StateName">Hessen</AdditionalData>
            <AdditionalData key="CountyName">Main-Taunus-Kreis</AdditionalData>
          </Address>
          <MapReference>
            <ReferenceId>52361527</ReferenceId>
            <MapId>UWAM15124</MapId>
            <MapVersion>Q1/2015</MapVersion>
            <Spot>0.15</Spot>
            <SideOfStreet>left</SideOfStreet>
            <CountryId>20147700</CountryId>
            <StateId>20160993</StateId>
            <CountyId>20161614</CountyId>
            <CityId>20161615</CityId>
          </MapReference>
        </Location>
      </Result>
      <Result>
        <Relevance>0.49</Relevance>
        <Distance>12.9</Distance>
        <MatchLevel>street</MatchLevel>
        <MatchQuality>
          <Country>1.0</Country>
          <State>1.0</State>
          <County>1.0</County>
          <City>1.0</City>
          <Street>1.0</Street>
          <PostalCode>1.0</PostalCode>
        </MatchQuality>
        <Location>
          <LocationId>NT_--A.v.nVr3c4vxvbu9swDA_l_52361473_L</LocationId>
          <LocationType>address</LocationType>
          <DisplayPosition>
            <Latitude>50.1416867</Latitude>
            <Longitude>8.5034944</Longitude>
          </DisplayPosition>
          <MapView>
            <TopLeft>
              <Latitude>50.14179</Latitude>
              <Longitude>8.50196</Longitude>
            </TopLeft>
            <BottomRight>
              <Latitude>50.14109</Latitude>
              <Longitude>8.50376</Longitude>
            </BottomRight>
          </MapView>
          <Address>
            <Label>Alleestraße, 65812 Bad Soden am Taunus, Deutschland</Label>
            <Country>DEU</Country>
            <State>Hessen</State>
            <County>Main-Taunus-Kreis</County>
            <City>Bad Soden am Taunus</City>
            <Street>Alleestraße</Street>
            <PostalCode>65812</PostalCode>
            <AdditionalData key="CountryName">Deutschland</AdditionalData>
            <AdditionalData key="StateName">Hessen</AdditionalData>
            <AdditionalData key="CountyName">Main-Taunus-Kreis</AdditionalData>
          </Address>
          <MapReference>
            <ReferenceId>52361473</ReferenceId>
            <MapId>UWAM15124</MapId>
            <MapVersion>Q1/2015</MapVersion>
            <Spot>0.85</Spot>
            <SideOfStreet>left</SideOfStreet>
            <CountryId>20147700</CountryId>
            <StateId>20160993</StateId>
            <CountyId>20161614</CountyId>
            <CityId>20161615</CityId>
          </MapReference>
        </Location>
      </Result>
    </View>
  </Response>
</ns2:Search>

Track Position including Nearest Address Information

The track position feature, which uses coordinates and a bearing to correctly identify the correct street being travelled upon, also adds the nearest address information to results, if requested.

The house number returned is based upon the nearest address on the road being travelled along. Preference is for house numbers that are on the driving side, relative to the bearing, in that country.

For example, in Germany cars drive on the right-hand side, so travelling south on a road will choose a house number right of the bearing.

This feature can be activated by using either of the following parameters:

locationattributes=(one of related.nearByAddress, rn, all)

The result provides the house number precision in a complete address in a separate Related block. Track position provides the nearest address but does not snap to this address like retrieveAddresses does.

The Related block contains the following additional details:

  • Type is always nearByAddress for trackPosition results.
  • MatchType is one of interpolated or pointAddress.
  • RouteDistance refers to the distance in meters from the snapped position on the link to the navigation position of the address. A user needs to travel this distance following the road to reach the entry of the house.
  • Direction refers to the bearing of the display position of the address relative to a 0 bearing point to true north. A user needs to turn her view clockwise into this direction to see the house.

Below is an example that retrieves the track position for a point and requests that the nearest address is added to the result:

https://reverse.geocoder.cit.api.here.com/6.2/reversegeocode.xml
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&gen=9
&pos=52.4662230,13.3282346,180
&mode=trackPosition
&locationattributes=rn

The result contains the street that is closest to the provided position and fits to the travel direction and it contains the nearest address information in the Related block.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:Search xmlns:ns2="http://www.navteq.com/lbsp/Search-Search/4">
  <Response>
    <MetaInfo>
      <Timestamp>2015-11-27T14:28:53.717Z</Timestamp>
      <NextPageInformation>2</NextPageInformation>
    </MetaInfo>
    <View xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:SearchResultsViewType">
      <ViewId>0</ViewId>
      <Result>
        <Relevance>0.99</Relevance>
        <Distance>0.4</Distance>
        <MatchLevel>street</MatchLevel>
        <MatchQuality>
          <Country>1.0</Country>
          <State>1.0</State>
          <County>1.0</County>
          <City>1.0</City>
          <District>1.0</District>
          <Street>1.0</Street>
          <PostalCode>1.0</PostalCode>
        </MatchQuality>
        <Location>
          <LocationId>NT_9rsoB5zwTm8gcUzZatY7mC_l_821537980_L</LocationId>
          <LocationType>address</LocationType>
          <DisplayPosition>
            <Latitude>52.466223</Latitude>
            <Longitude>13.32824</Longitude>
          </DisplayPosition>
          <NavigationPosition>
            <Latitude>52.466223</Latitude>
            <Longitude>13.32824</Longitude>
          </NavigationPosition>
          <MapView>
            ...
          </MapView>
          <Address>
            <Label>Bundesallee, 12161 Berlin, Deutschland</Label>
            <Country>DEU</Country>
            <State>Berlin</State>
            <County>Berlin</County>
            <City>Berlin</City>
            <District>Friedenau</District>
            <Street>Bundesallee</Street>
            <PostalCode>12161</PostalCode>
            <AdditionalData...</AdditionalData>
          </Address>
          <MapReference>
            ...
          </MapReference>
          <Related>
            <Type>nearByAddress</Type>
            <MatchType>pointAddress</MatchType>
            <RouteDistance>15.0</RouteDistance>
            <Direction>228.0</Direction>
            <Location>
              <LocationId>NT_9rsoB5zwTm8gcUzZatY7mC_5YD</LocationId>
              <LocationType>address</LocationType>
              <DisplayPosition>
                <Latitude>52.46609</Latitude>
                <Longitude>13.328</Longitude>
              </DisplayPosition>
              <NavigationPosition>
                <Latitude>52.46609</Latitude>
                <Longitude>13.32824</Longitude>
              </NavigationPosition>
              <Address>
                <Label>Bundesallee 96, 12161 Berlin, Germany</Label>
                <Country>DEU</Country>
                <State>Berlin</State>
                <County>Berlin</County>
                <City>Berlin</City>
                <District>Friedenau</District>
                <Street>Bundesallee</Street>
                <HouseNumber>96</HouseNumber>
                <PostalCode>12161</PostalCode>
                <AdditionalData...</AdditionalData>
              </Address>
              <MapReference>
                ...
              </MapReference>
            </Location>
          </Related>
        </Location>
      </Result>
    </View>
  </Response>
</ns2:Search>

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.