GuidesAPI Reference
Guides
  1. HERE Geocoding and Search API v7 Developer Guide
  2. HERE Geocoding and Search API v7 endpoints
  3. Geocode

Geocode an address with secondary unit

This tutorial demonstrates which options the /geocode endpoint provides to support geocoding of addresses with secondary units.

Procedure

The /geocode endpoint allows customer application to leverage secondary unit information, such as building, floor (level), and suite (unit). There are various use cases in which this information is helpful for the customer applications. One example is package delivery, where the end user wants to be directed to the exact building or a location within the building.

In map data, secondary units are represented by Micro Point Addresses (MPA). In comparison with a point address, a Micro Point Address has greater address detail and higher coordinate accuracy.

HERE Geocoding and Search supports Micro Point Addresses in the following countries: AUS, AUT, CAN, NZL, USA (with the territory of PRI).

MPA for package delivery - scenario A: pick a secondary unit from the list

📘

Note

This feature is released as RESTRICTED. See privilege.

In this scenario, the end user is searching for an address. Once the desired address is found, the application displays all unit names associated with that address.

The application can also display the location of the address and the locations of the units along with their respective names.

Then the end user can select a unit as their destination.

To support this scenario HERE Geocoding and Search provides showRelated=MPA functionality. With this functionality, the /geocode and lookup endpoints add to result items of resultType=houseNumber and houseNumberType=PA a block with a list of Micro Point Addresses, such as buildings, floors (levels), or suites (units), associated with this address.

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=2471+SW+58th+Mnr+Fort+Lauderdale+FL+33312
    &showRelated=MPA
    &apiKey={YOUR_API_KEY}

The following parameters are used:

  • showRelated - Allows enriching some types of response items with related items.
  • q - Enter a free-text query.
  • apiKey - Your API key.
📘

Note

This request uses API key authentication. For more information about authentication options on the HERE platform, see the Identity & Access Management Guide.

The house "2471 SW 58th Mnr" has two units "E" and "W" with the same access point but different display positions. The are now included into the response in the related block:

{
  "items": [
    {
      "title": "2471 SW 58th Mnr, Fort Lauderdale, FL 33312-6511, United States",
      "id": "here:af:streetsection:Ojge3i9Z2kNExmAnBAvyLB:CgcIBCDI1ps8EAEaBDI0NzE",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "2471 SW 58th Mnr, Fort Lauderdale, FL 33312-6511, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "FL",
        "state": "Florida",
        "county": "Broward",
        "city": "Fort Lauderdale",
        "street": "SW 58th Mnr",
        "postalCode": "33312-6511",
        "houseNumber": "2471"
      },
      "position": { "lat": 26.04932, "lng": -80.17407 },
      "access": [ { "lat": 26.04906, "lng": -80.17406 } ],
      "mapView": { "west": -80.17507, "south": 26.04842, "east": -80.17307, "north": 26.05022 },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "state": 1,
          "city": 1,
          "streets": [ 1 ],
          "houseNumber": 1,
          "postalCode": 1
        }
      },
      "related": [
        {
          "relationship": "MPA",
          "title": "2471 SW 58th Mnr Unit E, Fort Lauderdale, FL 33312-6511, United States",
          "id": "here:af:streetsection:Ojge3i9Z2kNExmAnBAvyLB:ChMIBCDI1ps8MgoKBggUIKW5fxAEEAEaBDI0NzE",
          "resultType": "houseNumber",
          "houseNumberType": "MPA",
          "position": { "lat": 26.04931, "lng": -80.17397 },
          "address": {
            "label": "2471 SW 58th Mnr Unit E, Fort Lauderdale, FL 33312-6511, United States",
            "unit": "E"
          }
        },
        {
          "relationship": "MPA",
          "title": "2471 SW 58th Mnr Unit W, Fort Lauderdale, FL 33312-6511, United States",
          "id": "here:af:streetsection:Ojge3i9Z2kNExmAnBAvyLB:ChMIBCDI1ps8MgoKBggUIJL8LRAEEAEaBDI0NzE",
          "resultType": "houseNumber",
          "houseNumberType": "MPA",
          "position": { "lat": 26.04931, "lng": -80.17406 },
          "address": {
            "label": "2471 SW 58th Mnr Unit W, Fort Lauderdale, FL 33312-6511, United States",
            "unit": "W"
          }
        }
      ]
    }
  ]
}

MPA for package delivery - scenario B: search for address plus unit name or number

📘

Note

This feature is released as RESTRICTED. See privilege.

In this scenario, the end user is searching for an address including unit name and expects to see in the result the full address, unit name, and location of the unit.

Since Micro Point Address results are required only for specific use cases and not all applications are designed to use them, this functionality needs to be activated by parameter: with=MPA. With this parameter, the geocode endpoint will try to match secondary unit information in the query to an address, house number, and unit name of a Micro Point Address:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=2471+SW+58th+Mnr+Unit+E+Fort+Lauderdale+FL+33312
    &with=MPA
    &apiKey={YOUR_API_KEY}

The following parameters are used:

  • with - Activate certain features or consider specific kinds of results, that would not be active or provided by default.
  • q - Enter a free-text query.
  • apiKey - Your API key.
📘

Note

This request uses API key authentication. For more information about authentication options on the HERE platform, see the Identity & Access Management Guide.

For this request the /geocode endpoint returns result with resultType=houseNumber and houseNumberType=MPA:

{
  "items": [
    {
      "title": "2471 SW 58th Mnr Unit E, Fort Lauderdale, FL 33312-6511, United States",
      "id": "here:af:streetsection:Ojge3i9Z2kNExmAnBAvyLB:ChUIBCDI1ps8MgwKCAgUILXouckCEAQQARoEMjQ3MQ",
      "resultType": "houseNumber",
      "houseNumberType": "MPA",
      "address": {
        "label": "2471 SW 58th Mnr Unit E, Fort Lauderdale, FL 33312-6511, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "FL",
        "state": "Florida",
        "county": "Broward",
        "city": "Fort Lauderdale",
        "street": "SW 58th Mnr",
        "postalCode": "33312-6511",
        "houseNumber": "2471",
        "unit": "E"
      },
      "position": { "lat": 26.04931, "lng": -80.17397 },
      "access": [{ "lat": 26.04906, "lng": -80.17396 }],
      "mapView": { "west": -80.17497, "south": 26.04841, "east": -80.17297, "north": 26.05021 },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "state": 1,
          "city": 1,
          "streets": [ 1 ],
          "houseNumber": 1,
          "postalCode": 1,
          "unit": 1
        }
      }
    }
  ]
}

The result items title, address label, and address block include the secondary unit information - in this case "Unit E".

Secondary unit for package delivery without MPA - scenario C: parse out and normalize secondary unit information from the query

In this scenario, the end user is also searching for an address including unit name, and expects to see the full address and unit name in the result. But the query intent is outside of the countries with MPA support or the customer application does not use the restricted MPA feature.

In this case, the /geocode endpoint still recognizes secondary unit information in the query and parses it out, so that it does not decrease the query score.

Since secondary unit information may have value for the end user even without exact coordinates, the customer application can request the /geocode endpoint to include recognized secondary units into the response:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=2471+SW+58th+Mnr+Unit+E+Fort+Lauderdale+FL+33312
    &show=parsing%2CsecondaryUnitInfo
    &apiKey={YOUR_API_KEY}

The following parameters are used:

  • show - Select additional fields to be rendered in the response.
    • parsing - the /geocode endpoint will provide information about how it parsed the request.
    • secondaryUnitInfo - the /geocode endpoint will return an additional block containing the normalized unit type and unit value for each matched unit designator.
  • q - Enter a free-text query.
  • apiKey - Your API key.
📘

Note

This request uses API key authentication. For more information about authentication options on the HERE platform, see the Identity & Access Management Guide.

For this request, the /geocode endpoint returns result with resultType=houseNumber and houseNumberType=PA. The result items title, address label, and address block do not include the secondary unit information. But parsing block contains it the same way as in the query.

And the result item contains new block secondaryUnitInfo where the same secondary unit information is represented in normalized form.

{
  "items": [
    {
      "title": "2471 SW 58th Mnr, Fort Lauderdale, FL 33312-6511, United States",
      "id": "here:af:streetsection:Ojge3i9Z2kNExmAnBAvyLB:CgcIBCDI1ps8EAEaBDI0NzE",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "2471 SW 58th Mnr, Fort Lauderdale, FL 33312-6511, United States",
        "countryCode": "USA",
        "countryName": "United States",
        "stateCode": "FL",
        "state": "Florida",
        "county": "Broward",
        "city": "Fort Lauderdale",
        "street": "SW 58th Mnr",
        "postalCode": "33312-6511",
        "houseNumber": "2471"
      },
      "position": { "lat": 26.04932, "lng": -80.17407 },
      "access": [{ "lat": 26.04906, "lng": -80.17406 }],
      "mapView": { "west": -80.17507, "south": 26.04842, "east": -80.17307, "north": 26.05022 },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "state": 1,
          "city": 1,
          "streets": [ 1 ],
          "houseNumber": 1,
          "postalCode": 1,
          "unit": 1
        }
      },
      "parsing": {
        "state": [{
            "start": 41,
            "end": 43,
            "value": "FL"
          }],
        ...
        "secondaryUnits": [{
            "start": 17,
            "end": 23,
            "value": "Unit+E"
          }]
      },
      "secondaryUnitInfo": [{
          "normalizedUnitType": "Unit",
          "unitValue": "e"
        }]
    }
  ]
}

HERE Geocoding and Search supports normalized secondary unit information in the following countries: AUS, AUT, BRA, CAN, ESP, FRA, GBR, HKG, IDN, IND, MEX, NZL, TUR, TWN, USA (with the territory of PRI).

Additional information

For more information about the /geocode endpoint parameters, see the API Reference.

Updated last month