How to find an address using the Azure Maps search service
- 6 minutes to read
-
Contributors
The Maps search service is a RESTful set of APIs designed for developers to search for addresses, places, points of interest, business listings, and other geographic information. The service assigns a latitude/longitude to a specific address, cross street, geographic feature, or point of interest (POI). Latitude and longitude values returned by the search can be used as parameters in other Maps services like route and traffic flow.
Prerequisites
To make any calls to the Maps service APIs, you need a Maps account and key. For information on creating an account and retrieving a key, see How to manage your Azure Maps account and keys.
This article uses the Postman app to build REST calls. You can use any API development environment that you prefer.
Using fuzzy search
The default API for the search service is fuzzy search, which handles inputs of any combination of address or POI tokens. This search API is the canonical 'single-line search' and is useful when you do not know what your user inputs as a search query. The fuzzy search API is a combination of POI search and geocoding. The API can also be weighted with a contextual position (lat./lon. pair), fully constrained by a coordinate and radius, or it can be executed more generally without any geo biasing anchor point.
Most Search queries default to 'maxFuzzyLevel=1' to gain performance and reduce unusual results. This default can be overridden as needed per request by passing in the query parameter 'maxFuzzyLevel=2' or '3'.
Search for an address using Fuzzy Search
Open the Postman app, click New | Create New, and select GET request. Enter a Request name of Fuzzy search, select a collection or folder to save it to, and click Save.
On the Builder tab, select the GET HTTP method and enter the request URL for your API endpoint.
Parameter Suggested value HTTP method GET Request URL https://atlas.microsoft.com/search/fuzzy/json? Authorization No Auth The json attribute in the URL path determines the response format. You are using json throughout this article for ease of use and readability. You can find the available response formats in the Get Search Fuzzy definition of the Maps Functional API reference.
Click Params, and enter the following Key / Value pairs to use as query or path parameters in the request URL:
Key Value api-version 1.0 subscription-key <your Azure Maps key> query pizza Click Send and review the response body.
The ambiguous query string of "pizza" returned 10 point of interest (POI) results with categories falling in "pizza" and "restaurant". Each result returns a street address, latitude / longitude values, view port, and entry points for the location.
The results are varied for this query, not tied to any particular reference location. You can use the countrySet parameter to specify only the countries for which your application needs coverage, as the default behavior is to search the entire world, potentially returning unnecessary results.
Add the following Key / Value pair to the Params section and click Send:
Key Value countrySet US The results are now bounded by the country code and the query returns pizza restaurants in the United States.
To provide results oriented on a particular location, you can query a point of interest and use the returned latitude and longitude values in your call to the Fuzzy Search service. In this case, you used the Search service to return the location of the Seattle Space Needle and used the lat. / lon. values to orient the search.
In Params, enter the following Key / Value pairs and click Send:
Key Value lat 47.62039 lon -122.34928
Search for address properties and coordinates
You can pass a complete or partial street address to the search address API and receive a response that includes detailed address properties such as municipality or subdivision, as well as positional values in latitude and longitude.
- In Postman, click New Request | GET request and name it Address Search.
On the Builder tab, select the GET HTTP method, enter the request URL for your API endpoint, and select an authorization protocol, if any.
Parameter Suggested value HTTP method GET Request URL https://atlas.microsoft.com/search/address/json? Authorization No Auth Click Params, and enter the following Key / Value pairs to use as query or path parameters in the request URL:
Key Value api-version 1.0 subscription-key <your Azure Maps key> query 400 Broad St, Seattle, WA 98109 Click Send and review the response body.
In this case, you specified a complete address query and receive a single result in the response body.
In Params, edit the query string to the following value:
400 Broad, SeattleAdd the following Key / Value pair to the Params section and click Send:
Key Value typeahead true The typeahead flag tells the Address Search API to treat the query as a partial input and return an array of predictive values.
Search for a street address using Reverse Address Search
In Postman, click New Request | GET request and name it Reverse Address Search.
On the Builder tab, select the GET HTTP method and enter the request URL for your API endpoint.
Parameter Suggested value HTTP method GET Request URL https://atlas.microsoft.com/search/address/reverse/json? Authorization No Auth Click Params, and enter the following Key / Value pairs to use as query or path parameters in the request URL:
Key Value api-version 1.0 subscription-key <your Azure Maps key> query 47.59093,-122.33263 Click Send and review the response body.
The response includes the POI entry for Safeco Field with a poi category of "stadium".
Add the following Key / Value pair to the Params section and click Send:
Key Value number true If the number query parameter is sent with the request, the response may include the side of the street (Left/Right) and also an offset position for that number.
Add the following Key / Value pair to the Params section and click Send:
Key Value spatialKeys true When the spatialKeys query parameter is set, the response contains proprietary geo-spatial key information for a specified location.
Add the following Key / Value pair to the Params section and click Send:
Key Value returnSpeedLimit true When the returnSpeedLimit query parameter is set, the response return of the posted speed limit.
Add the following Key / Value pair to the Params section and click Send:
Key Value returnRoadUse true When the returnRoadUse query parameter is set, the response returns the road use array for reversegeocodes at street level.
Add the following Key / Value pair to the Params section and click Send:
Key Value roadUse true You can restrict the reverse geocode query to a specific type of road use using the roadUse query parameter.
Search for the cross street using Reverse Address Cross Street Search
In Postman, click New Request | GET request and name it Reverse Address Cross Street Search.
On the Builder tab, select the GET HTTP method and enter the request URL for your API endpoint.
Parameter Suggested value HTTP method GET Request URL https://atlas.microsoft.com/search/address/reverse/crossstreet/json? Authorization No Auth Click Params, and enter the following Key / Value pairs to use as query or path parameters in the request URL:
Key Value api-version 1.0 subscription-key <your Azure Maps key> query 47.59093,-122.33263 Click Send and review the response body.
Next steps
- Explore the Azure Maps search service API documentation