Response enrichment with map references

By using the request parameter showMapReferences, developers can enhance specific response items with map references, to enable connection with other services or data applications.

The following table lists currently supported values for showMapReferences:

`showMapReferences` value	endpoints	maturity privilege	Description
`segments`	`/autosuggest`, `/geocode`, `/revgeocode`, `/multi-revgeocode`, `/lookup`	GA	For `resultType=houseNumber`, `resultType=street` or `resultType=place` result item, returns the segment reference from the result's access position. Exception: In Japan, segment reference is only returned for `resultType=street`. Note: The previous parameter `show=hmcReference` is deprecated, and is replaced by `showMapReferences=segments` which serves the same purpose. Multiple segment references could be returned if the result has multiple access positions. For more details, see the API Reference.
`links`	`/geocode`, `/revgeocode`, `/multi-revgeocode`, `/lookup`	GA	For `resultType=houseNumber`, `resultType=street` or `resultType=place` result item, returns the link reference from the result's access position. Exception: In Japan, link reference is not returned. Note: Multiple link references could be returned if the result has multiple access positions. For more details, see the API Reference.
`pointAddress`	`/autosuggest`, `/geocode`, `/revgeocode`, `/multi-revgeocode`, `/lookup`	GA	For `resultType=houseNumber`and `houseNumberType=PA` result item, includes the point address identifier, formatted according to the Here Map Content specification.
`microPointAddress`	`/geocode`, `/revgeocode`, `/multi-revgeocode`, `/lookup`	GA, RESTRICTED	For `resultType=houseNumber`and `houseNumberType=MPA` result item, includes the micro point address identifier, formatted according to the Here Map Content specification.
`adminIds`	`/autosuggest`, `/geocode`, `/revgeocode`, `/multi-revgeocode`, `/lookup`	GA	Returns the identifier of each administrative level in the `address` block for the result item, formatted according to the Here Map Content specification.
`cmVersion`	`/geocode`, `/revgeocode`, `/multi-revgeocode`, `/lookup`	GA	Returns the core map version number of the region where the result item is located. Map version details (DVN) contains the baseline for the map schema and an identifier for the weekly or quarterly update. Format: YYQ<week/quarter>, for example: 24121 (map schema: Q1/2024, weekly update 21) Exception: The feature is not supported for Japan map content.

Example of a /revgeocode endpoint response with showMapReferences=segments,links,pointAddress,adminIds,cmVersion:

GET https://revgeocode.search.hereapi.com/v1/
    revgeocode
    ?at=52.518333,13.408333
    &types=address
    &lang=en-US
    &showMapReferences=segments,links,pointAddress,adminIds,cmVersion
    &apiKey={YOUR_API_KEY}

{
          "title": "Rathausstraße 15, 10178 Berlin, Germany",
          "id": "here:af:streetsection:2pGteqRk7Ros60IJL5KyEA:CgcIBCCk6s5QEAEaAjE1",
          "resultType": "houseNumber",
          "houseNumberType": "PA",
          "address": {
              "label": "Rathausstraße 15, 10178 Berlin, Germany",
              "countryCode": "DEU",
              "countryName": "Germany",
              "stateCode": "BE",
              "state": "Berlin",
              "countyCode": "B",
              "county": "Berlin",
              "city": "Berlin",
              "district": "Mitte",
              "street": "Rathausstraße",
              "postalCode": "10178",
              "houseNumber": "15"
          },
          "position": {"lat": 52.51856, "lng": 13.40821},
          "access": [{"lat": 52.51874, "lng": 13.40796}],
          "distance": 27,
          "mapView": {...},
          "mapReferences": {
              "links": [
                  {
                      "cmId": "733328455",
                      "side": "right"
                  }
              ],
              "pointAddress": {
                  "hmcId": "here:cm:pointaddress:169063716"
              },
              "segments": [
                  {
                      "ref": "here:cm:segment:783444988#0.481734",
                      "side": "left"
                  }
              ],
              "country": {
                  "hmcId": "here:cm:namedplace:20147700"
              },
              "state": {
                  "hmcId": "here:cm:namedplace:20187401"
              },
              "county": {
                  "hmcId": "here:cm:namedplace:20187402"
              },
              "city": {
                  "hmcId": "here:cm:namedplace:20187403"
              },
              "district": {
                  "hmcId": "here:cm:namedplace:20187417"
              },
              "cmVersion": {
                  "region": "WEU",
                  "dvn": "24121"
              }
          }
}

📘
Note

linkId is deprecated and removed, it's replaced by cmId.

sideOfLink is deprecated and removed, it's replaced by side.

link.side and segment.side for the same entity are the same if the link direction aligns with the segment direction. However, they can differ if the link direction does not match the segment direction.

Forward link direction is defined as the direction from the reference node to the non-reference node. If latitude of reference node is smaller than non-reference node, the direction is from southernmost to northernmost. If latitude of both end nodes are identical and their longitudes differ, the direction is from westernmost node to easternmost node.

Forward segment direction is defined as the direction from the segment start node to the segment end node.

The previous parameter show=hmcReference is deprecated and replaced by showMapReferences=segments which serves the same purpose.