Azure Maps API - require exact match from /address/structured

Question

My use case is simple; I have a country code and a postal code. I want lat/lon back. Take the following query:

https://atlas.microsoft.com/search/address/structured/json?subscription-key={key}&api-version=1.0&postalCode=Thomas&countryCode=US

This returns 5986 results, the first of which is a hit for Thomas, OK. I provided a postalCode explicitly, so I'm not sure why a fuzzy search is being performed. On top of that, I see no way to filter this result out as incorrect. I noticed the "fuzzyLevel" field in the "summary" section and thought I could perhaps use that. Unfortunately, the docs (useless autogenerated nonsense) have this to say about it:

fuzzyLevel    integer    FuzzyLevel property   

`Well that's certainly helpful. I played around with it but, unfortunately, the query aboev comes back with "fuzzyLevel: 1", the same as an exact match. Using the postalCode "error" returns a 2, so that can be filtered, but not universally helpful. I also noticed that there is no postalCode included in the "address" response for postalCode: Thomas. I of course have no idea if I can count on this behavior though, so I am hesitant to rely upon it. Is there a simple way I can request that only an exact match on the field(s) I provide be used, otherwise return nothing? I have no use for these wild guesses.

Would filtering by result.entityType.PostalCodeArea be correct here?

Edit: Nope! Some responses don't have an entityType field at all! e.g. E6L 2H2, CA

Answer 1

Thanks @QuantumCache , I appreciate it, but that's not quite my issue. My problem is that I don't know of a reliable way to validate that the combination of post/country code found a "strong" match. What I'd like to do is return an error if there is no match on those, but the API returns a result anyway by matching street name/munici[pality/whatever. I'm not interested in that sort of free form, fuzzy matching.

Here's our use case: We need to determine how old a blood sample is. A lab operator enters a country code and a postal code. They expect back a time span. In order to calculate that span we need to know when it was shipped, including time zone information. So, we use azure maps to get the local time in the shipping location as well as the receiving location and do some simple math.

If someone enters "Thomas" as the postal code it is obviously a typo and I need to bail on the entire thing, not return the time from e.g. Thomas OK. Essentially, I don't want the API to be tolerant of typos and incomplete information, or find a way to determine whether or not it got an exact hit.

Answer 2

Hello @Edward Swangren ,

So one of your main questions is that the Azure Maps API search should return all the postalCode when its fuzzy level=1, right?

I think the below image shows the entire list of Thomas, OK Postal codes. Just for the reference.

Repro of the issues reported in your question is as below, please confirm if we are on the same page for these.../

using 'error', as reported in your question.

I hope you have already seen this document on 'Get Search Fuzzy' , which neither shows the postal code in address response.

And we see the response with postal code for 'Get Search Address Structured'.

Answer 3

Thanks @Edward Swangren ,

Updated:
In short the confirmation is 'No'

----------

Below is the response from the Microsoft Product Group Team, I hope this helps with your query.

• We will only return error codes when the query is invalid, e.g. it has invalid parameters, or it does not follow the correct format.
• Azure Maps Search services are designed to return coordinate location for a given address excluding the unit level, and they can be used for address validation.
• Azure Maps can provide an address that has spelling mistakes removed. The returned data follows the standard format for the specific country, e.g. in the US and in Finland we have different formats.
• Our Geocoder API’s do provide a list of addresses in the response, but this will require some human intervention to choose which of these response makes the most sense. This works well in forms where the customer can choose the right address.

For example, if we provide 1, Main Street, Seattle – it will return 2 responses:

1, Main Street, N Seattle

and

1, Main Street, S Seattle.

We cannot guarantee the results if inaccurate input parameters are sent to us.
In the example, the result type is now municipality, and for municipalities, we don't return postal codes, because one municipality can cover hundreds of postal codes.

Please let us know if you need further help in this matter.
Please accept helpful responses as 'Answer', which will be helpful to others as well with similar question.

Answer 4

As 2021, It seems like the endpoint now takes the "entityType" url param?

https://atlas.microsoft.com/search/address/structured/json?api-version=1.0&subscription-key=****&postalCode=45875&countryCode=US&entityType=PostalCodeArea

This works for me, but It seems like the documentation does not make any mention about it??? https://learn.microsoft.com/en-us/rest/api/maps/search/get-search-address-structured

Can someone clarify this?