Structured Address Search API returns incorrect top-ranked result

Question

When querying the structured address search endpoint with explicit municipality, countrySubdivision, and postalCode parameters, the API returns a result from a completely different state with a higher confidence score than a result matching the specified municipality/state/postal code.

Repro steps:

1. Call: GET /search/address/structured/json?api-version=1.0&countryCode=US&streetNumber=170&streetName=Buc-ee's Blvd&municipality=Kodak&countrySubdivision=Tennessee&postalCode=37764&limit=2
2. Result #1 returned: 170 Buc-Ee's Boulevard, Melissa, TX 75454 — score 0.592 (municipality/state do not match input)
3. Result #2 returned: Sunrise Boulevard, Kodak, TN 37764 — score 0.466 (municipality/postal code match input, but street name does not match at all)

Expected behavior: When municipality, state, and postal code are all explicitly supplied and match a result, that result should be weighted at least as highly as — or filterable above — results that only match on street name but fail on location fields entirely.

Question for support: Is there a recommended parameter (e.g., stricter fuzzy level, structured-only matching flag) to force geographic fields to take precedence over street-name fuzzy matches? Also requesting confirmation on whether "170 Buc-ee's Blvd, Kodak, TN 37764" exists in Azure Maps' current address dataset at all, since the Kodak result didn't match the street name.

Answer 1

hi Sanket Patel & thx for sharing urs issue here at Q&A portal,

there doesn’t appear to be a parameter in the v1.0 Structured Address Search API that forces municipality/state/postal code to be treated as strict filters. The service still ranks candidates using its internal matching logic, so a strong street-name match can appear above a geographically correct but incomplete result. fuzzyLevel isn’t available for the structured address endpoint, and the returned score shouldn’t be treated as a strict address-validity score. https://learn.microsoft.com/rest/api/maps/search/get-search-address-structured?view=rest-maps-1.0

A practical workaround is to validate the returned fields client-side and reject results where municipality, countrySubdivision, or postalCode don’t match the supplied values. You can also try the newer Geocoding API and compare the matchCodes/confidence data https://learn.microsoft.com/rest/api/maps/search/get-geocoding?view=rest-maps-2026-01-01

Whether 170 Buc-ee's Blvd, Kodak, TN 37764 exists in the current Azure Maps dataset can’t be confirmed from the request alone. Since the API returns no matching street-level result, it may be missing, indexed differently, or simply not recognized yet. The Texas result ranking above the Tennessee candidate is still poor behavior for a structured query. I’d send this exact repro to Azure Maps support so the data/search team can check both the ranking and source dataset.

rgds,

Alex

&

If my answer was helpful pls mark it and additional thx if u follow me at Q&A portal

and at my blog https://ctrlaltdel.blog/

 

Answer 2

Hello @Sanket Patel,

Welcome to Microsoft Q&A .Thank you for reaching out to us.

Based on the review, the observed behavior appears to be related to the relevance-based candidate ranking approach used by Azure Maps Structured Address Search (v1.0) rather than an issue with the request format. The endpoint evaluates multiple address components when ranking candidates, which means a result with a stronger street-level match can rank higher than a result that matches administrative fields such as municipality, state, or postal code but has a weaker street match.

The score value returned by the API should therefore be interpreted as a relative ranking score among candidates returned in the same response. It should not be treated as an address validity, accuracy, or confidence score. A higher score does not necessarily indicate that a result is geographically more correct; it indicates that the candidate received a higher relevance ranking for that query.

1. Availability of strict filtering or fuzzy matching controls Regarding whether municipality, state, or postal code can be enforced as strict filters: Currently, the Structured Address Search (v1.0) API does not provide a documented parameter that allows:
   • municipality
   • countrySubdivision
   • postalCode
   to be treated as mandatory filters. There is also no documented option for:
   • Exact-match mode
   • Structured-only matching mode
   • Forcing administrative fields to take precedence during candidate ranking
   Additionally, minFuzzyLevel and maxFuzzyLevel controls are not available for this endpoint, so fuzzy matching behavior cannot be adjusted through request parameters.Regarding whether municipality, state, or postal code can be enforced as strict filters: Currently, the Structured Address Search (v1.0) API does not provide a documented parameter that allows:
   • municipality
   • countrySubdivision
   • postalCode
   to be treated as mandatory filters. There is also no documented option for:
   • Exact-match mode
   • Structured-only matching mode
   • Forcing administrative fields to take precedence during candidate ranking
   Additionally, minFuzzyLevel and maxFuzzyLevel controls are not available for this endpoint, so fuzzy matching behavior cannot be adjusted through request parameters.
2. Recommended approach for stricter address validation For workflows where geographic consistency is critical, the recommended approach is to treat search responses as candidate results and apply validation logic before accepting an address. Suggested validation checks:
   • Country Code = US
   • Municipality = Kodak
   • State = TN / Tennessee
   • Postal Code = 37764
   • Street Name matches expected variations:
   • Buc-ee's Blvd
   • Buc-ee's Boulevard
   • Bucees Blvd
   • Street Number = 170 (when available)
   If none of the returned candidates satisfy the required conditions, returning a response such as "No exact address match found" would provide more predictable behavior than automatically accepting the highest-ranked candidate.

Please check if the following steps help-

1. Increasing the result limit:
   • Test with limit=10 or limit=20.
   • Review additional candidates beyond the first two results.
2. Testing address formatting variations:
   • 170 Buc-ee's Blvd, Kodak, TN 37764
   • 170 Buc-ee's Boulevard, Kodak, TN 37764
   • 170 Bucees Blvd, Kodak, TN 37764
3. Comparing returned candidate fields:
   • Municipality
   • State
   • Postal code
   • Street name
   • Street number
   • Address type
4. Confirm whether any candidate is returned as an Address-level match rather than a broader street or locality-level match. These checks can help determine whether the address is missing, normalized differently, or represented at a broader geographic level.

Evaluation of the newer Geocoding API

For scenarios requiring more control over address acceptance decisions, evaluating the Azure Maps Geocoding API (2026-01-01) is recommended.

The newer API provides additional match information, including:

• confidence
• matchCodes
• Feature type

These properties allow applications to distinguish between precise address matches and broader or ambiguous results.

A practical acceptance policy could include:

• Feature type = Address
• matchCodes contains Good
• matchCodes does not contain UpHierarchy
• Confidence = High or Medium
• Returned locality matches the requested municipality
• Returned administrative district matches the requested state
• Returned postal code matches the requested postal code

These checks should be implemented as application-side validation rules. The API metadata provides additional signals to make informed acceptance decisions rather than relying only on ranking order.

Verifying whether "170 Buc-ee's Blvd, Kodak, TN 37764" exists in the dataset

The current Structured Address Search response alone is not sufficient to conclusively confirm whether this address exists in the Azure Maps searchable dataset.

The observed behavior could indicate several possibilities:

• The address is not currently available as a point address.
• The address is indexed using a different normalization or format.
• The address is only represented at a broader geographic level.
• The address was not returned within the current result set.

Recommended validation steps:

1. Submit the same address using the Geocoding API.
2. Review:
   • Confidence value
   • Match codes
   • Feature type
3. Confirm whether an Address-level result is returned.
4. If known coordinates are available, perform Reverse Geocoding and compare the returned address details.

The following references might be helpful , please check them out

• Search - Get Search Address Structured - REST API (Azure Maps) | Microsoft Learn
• Search - Get Geocoding - REST API (Azure Maps) | Microsoft Learn
• Search - Get Reverse Geocoding - REST API (Azure Maps) | Microsoft Learn
• Migrate Azure Maps Search 1.0 APIs - Microsoft Azure Maps | Microsoft Learn
• Best practices for Azure Maps Search service - Microsoft Azure Maps | Microsoft Learn

Thank you

 

Please "Accept" the answer with an "Upvote" if the response was helpful. This will be benefitting other community members who face the same issue.