Azure Maps stopped recognizing Åland addresses

Question

Azure Maps stopped recognizing Åland addresses

Lars Rönnbäck 0

A few weeks ago we were looking up addresses on Åland using Azure Maps, and it worked fine. Since about two weeks though, every Åland address is returned as UpHierarcy and Low confidence. We are using https://atlas.microsoft.com and the "geocode" endpoint with API version 2026-01-01.

Is this a known regression? Is there a workaround?

The input address is sent using addressLine = "Full street address, postal code, city, without country code" and countryRegion = "AX" (switching to "FI" gives the same result).

Example result:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          19.943862915039062,
          60.21662139892578
        ]
      },
      "bbox": [
        19.08319091796875,
        59.45414733886719,
        21.34565544128418,
        60.87665939331055
      ],
      "properties": {
        "type": "CountryRegion",
        "confidence": "Low",
        "matchCodes": [
          "UpHierarchy"
        ],
        "geocodePoints": [
          {
            "calculationMethod": "",
            "usageTypes": [
              "Display"
            ],
            "geometry": {
              "type": "Point",
              "coordinates": [
                19.943862915039062,
                60.21662139892578
              ]
            }
          }
        ],
        "address": {
          "countryRegion": {
            "name": "Åland Islands",
            "ISO": "AX"
          },
          "formattedAddress": "Åland Islands"
        }
      }
    }
  ]
}

rbrundritt 21,726 Reputation points Volunteer Moderator

2026-11-04T18:17:56.4033333+00:00

I haven't heard of any issue related to Aland recently. Can you provide a sample address where you are seeing this occur. I'll coordinate with the Azure Maps support team to look into this.

1 answer

Your answer

rbrundritt 21,726 Reputation points Volunteer Moderator

2026-11-04T18:17:56.4033333+00:00

I haven't heard of any issue related to Aland recently. Can you provide a sample address where you are seeing this occur. I'll coordinate with the Azure Maps support team to look into this.

Answer 1

The returned result indicates the service is not finding the requested address at street-level granularity and is falling back up the geographic hierarchy to CountryRegion. In Azure Maps, matchCodes: ["UpHierarchy"] means the service could not match the specificity implied by the request and returned a broader location instead. A Low confidence result should be treated as not acceptable for an exact-address workflow.

The available documentation does not identify this as a known regression.

Supported workarounds:

Use structured address parameters only when the address components are known separately. If the current addressLine contains street address, postal code, and city combined into one field, split them into structured fields such as:
- addressLine = street address only
- postalCode = postal code
- locality = city
- countryRegion = AX or FI
Structured parameters are recommended over a single free-form input because they typically produce more accurate results.
Do not combine query with structured fields. If testing alternatives, use either:
- structured fields, or
- query with geographic bias such as bbox
Passing structured fields together with query can cause conflicting-parameters errors.
If query must be used, add geographic context with bbox in [lon1,lat1,lon2,lat2] format to bias results toward Åland. This is the documented way to guide query-based searches toward the expected area.
Filter results using all three signals together:
- confidence
- matchCodes
- properties.type
For exact address UX, reject results when:
- confidence is Low
- matchCodes contains UpHierarchy
- type is broader than Address, such as CountryRegion
Handle empty or rejected results as valid no-match outcomes rather than service failures. The guidance explicitly recommends avoiding forced matches for low-quality input because that can introduce incorrect location data.
Verify coverage expectations for Åland. The coverage table shows Finland has address-point, house-number, street-level, city-level, and POI coverage, but Åland is not listed separately in the provided coverage tables. That means the available material supports Finland coverage generally, but does not confirm Åland-specific behavior.

References: