Merge pull request #306027 from stevemunk/search-v2-how-to

Search v2 how to

Author: JamesJBarnett

articles/azure-maps/how-to-search-for-address.md

@@ -1,24 +1,27 @@
 ---
 title: Search for a location using Azure Maps Search services
 description: Learn about the Azure Maps Search service. See how to use this set of APIs for geocoding, reverse geocoding, fuzzy searches, and reverse cross street searches.
-author: farazgis
-ms.author: fsiddiqui
-ms.date: 8/9/2024
+author: sinnypan
+ms.author: sipa
+ms.date: 9/24/2025
 ms.topic: how-to
 ms.service: azure-maps
-ms.subservice: routing
+ms.subservice: search
+zone_pivot_groups: azure-maps-search
 ---
 
 # Search for a location using Azure Maps Search services
 
 The [Search] service is a set of RESTful APIs designed to help developers search addresses, places, and business listings by name, category, and other geographic information. In addition to supporting traditional geocoding, services can also reverse geocode addresses and cross streets based on latitudes and longitudes. Latitude and longitude values returned by the search can be used as parameters in other Azure Maps services, such as [Route] and [Weather].
 
+:::zone pivot="search-previous"
+
 This article demonstrates how to:
 
 * Request latitude and longitude coordinates for an address (geocode address location) by using [Search Address].
 * Search for an address or Point of Interest (POI) using [Fuzzy Search].
 * Use [Reverse Address Search] to translate coordinate location to street address.
-* Translate coordinate location into a human understandable cross street using [Search Address Reverse Cross Street], most often needed in tracking applications that receive a GPS feed from a device or asset, and wish to know where the coordinate is located.
+* Use the [Search Address Reverse Cross Street] API to convert a coordinate location into a human-readable cross street. This is especially useful in tracking applications that receive GPS data from devices or assets and need to determine the nearest street-level location for those coordinates.
 
 ## Prerequisites
 
@@ -27,9 +30,9 @@ This article demonstrates how to:
 
 >[!IMPORTANT]
 >
-> In the URL examples in this article you will need to replace `{Your-Azure-Maps-Subscription-key}` with your Azure Maps subscription key.
+> In the URL examples in this article, you need to replace `{Your-Azure-Maps-Subscription-key}` with your Azure Maps subscription key.
 
-This article uses the [bruno] application, but you can choose a different API development environment.
+This article uses the [Bruno] application, but you can choose a different API development environment.
 
 ## Request latitude and longitude for an address (geocoding)
 
@@ -38,7 +41,9 @@ The example in this section uses [Get Search Address] to convert an address into
 > [!TIP]
 > If you have a set of addresses to geocode, you can use [Post Search Address Batch] to send a batch of queries in a single request.
 
-1. Open the bruno app, select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
+1. Open the [Bruno] application.
+
+1. Select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
 
 1. Select the **GET** HTTP method in the **URL** drop-down list, then enter the following URL:
 
@@ -74,7 +79,9 @@ The example in this section uses `Fuzzy Search` to search the entire world for *
 > [!IMPORTANT]
 > To geobias results to the relevant area for your users, always add as many location details as possible. For more information, see [Best Practices for Search].
 
-1. Open the bruno app, select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
+1. Open the [Bruno] application.
+
+1. Select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
 
 1. Select the **GET** HTTP method in the **URL** drop-down list, then enter the following URL:
 
@@ -122,15 +129,17 @@ The example in this section uses `Fuzzy Search` to search the entire world for *
 
 This example demonstrates making reverse searches using a few of the optional parameters that are available. For the full list of optional parameters, see [Reverse Search Parameters].
 
-1. Open the bruno app, select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
+1. Open the [Bruno] application.
+
+1. Select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
 
 1. Select the **GET** HTTP method in the **URL** drop-down list, then enter the following URL:
 
     ```http
     https://atlas.microsoft.com/search/address/reverse/json?api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=47.591180,-122.332700
     ```
 
-1. Select the run button, and review the response body. You should see one query result. The response includes key address information about Safeco Field.
+1. Select the run button, and review the response body. You should see one query result. The response includes key address information about T-Mobile Park.
   
 1. Next, add the following key/value pairs to the **Params** section:
 
@@ -145,20 +154,22 @@ This example demonstrates making reverse searches using a few of the optional pa
 
 1. Select the run button, and review the response body.
 
-1. Next, add the `entityType` key, and set its value to `Municipality`. The `entityType` key overrides the `returnMatchType` key in the previous step. `returnSpeedLimit` and `returnRoadUse` also need removed since you're requesting information about the municipality.  For all possible entity types, see [Entity Types].
+1. Next, add the `entityType` key, and set its value to `Municipality`. The `entityType` key overrides the `returnMatchType` key in the previous step. `returnSpeedLimit` and `returnRoadUse` also need removed since you're requesting information about the municipality. For all possible entity types, see [Entity Types].
 
     :::image type="content" source="./media/how-to-search-for-address/search-reverse-entity-type.png" alt-text="Search reverse entityType.":::
 
-1. Select the run button. Compare the results to the results returned in step 5.  Because the requested entity type is now `municipality`, the response doesn't include street address information. Also, the returned `geometryId` can be used to request boundary polygon through Azure Maps Get [Search Polygon API].
+1. Select the run button. Compare the results to the results returned in step 5. Because the requested entity type is now `municipality`, the response doesn't include street address information. Also, the returned `geometryId` can be used to request boundary polygon through Azure Maps Get [Search Polygon API].
 
 > [!TIP]
-> For more information on these as well as other parameters, see [Reverse Search Parameters].
+> For more information, see [Reverse Search Parameters].
 
 ## Search for cross street using Reverse Address Cross Street Search
 
 This example demonstrates how to search for a cross street based on the coordinates of an address.
 
-1. Open the bruno app, select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
+1. Open the [Bruno] application.
+
+1. Select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
 
 1. Select the **GET** HTTP method in the **URL** drop-down list, then enter the following URL:
   
@@ -168,6 +179,194 @@ This example demonstrates how to search for a cross street based on the coordina
 
 1. Select the run button, and review the response body. Notice that the response contains a `crossStreet` value of `South Atlantic Street`.
 
+:::zone-end
+
+:::zone pivot="search-latest"
+
+This article demonstrates how to:
+
+* Request latitude and longitude coordinates for an address (geocode address location) by using [Get Geocoding].
+* Search for a partial address using [Get Geocode Autocomplete].
+* Use [Get Reverse Geocoding] to translate coordinate location to street address.
+* Translate coordinate location into a human understandable cross street using [Get Reverse Geocoding], most often needed in tracking applications that receive a GPS feed from a device or asset, and wish to know where the coordinate is located.
+
+## Prerequisites
+
+* An [Azure Maps account]
+* A [subscription key]
+
+>[!IMPORTANT]
+>
+> In the URL examples in this article, you need to replace `{Your-Azure-Maps-Subscription-key}` with your Azure Maps subscription key.
+
+This article uses the [Bruno] application, but you can choose a different API development environment.
+
+## Request coordinates for an address using Get Geocoding
+
+The example in this section uses [Get Geocoding] to convert an address into latitude and longitude coordinates. This process is also called *geocoding*. In addition to returning the coordinates, the response also returns detailed address properties such as street, postal code, municipality, and country/region information.
+
+> [!TIP]
+> If you have a set of addresses to geocode, you can use [Get Geocoding Batch] to send a batch of queries in a single request.
+
+1. Open the [Bruno] application.
+
+1. Select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
+
+1. Select the **GET** HTTP method in the **URL** drop-down list, then enter the following URL:
+
+    ```http
+    GET https://atlas.microsoft.com/geocode?api-version=2025-01-01&subscription-key={Your-Azure-Maps-Subscription-key}&query=400 Broad St, Seattle, WA 98109
+    ```
+
+1. Select the **Create** button.
+
+1. Select the run button.
+
+    This request searches for a specific address: `400 Broad St, Seattle, WA 98109`. Next, search an address that has more than one possible location.
+
+1. In the **Params** section, change the `query` key to `400 Broad, Seattle`, then select the run button.
+
+1. Next, try setting the `query` key to `400 Broa`, then select the run button.
+
+   The response includes results from multiple countries/regions. To [geobias] results to the relevant area for your users, always add as many location details as possible to the request.
+
+## Use Get Geocode Autocomplete for partial address search
+
+The [Get Geocode Autocomplete] API supports both single-line and free-form address inputs, making it ideal for scenarios where a complete address is unavailable. You can submit either a full or partial address as the query. To enhance the accuracy and relevance of the results, it's recommended to constrain the search by specifying coordinates or a bounding box.
+
+This example demonstrates how to use the Get Geocode Autocomplete API to search the entire North American continent for partial input like "university of w." It then shows how to narrow the search scope to a specific country or region using the `countryRegion` parameter. Finally, it demonstrates how to use the `coordinates` parameter to focus the search to a specific area.
+
+> [!IMPORTANT]
+> To geobias results to the relevant area for your users, always add as many location details as possible. For more information, see [Best Practices for Search].
+
+1. Open the [Bruno] application.
+
+1. Select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
+
+1. Select the **GET** HTTP method in the **URL** drop-down list, then enter the following URL:
+
+    ```http
+    https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=university of w&bbox=-168,-52,5,84&subscription-key={Your-Azure-Maps-Subscription-key}
+    ```
+
+1. Select the run button, then review the response body.
+
+   > [!NOTE]
+    > The `bbox` parameter in the URL defines a bounding box that encompasses **Canada**, the **United States**, **Mexico**, **Greenland**, and parts of the **Caribbean**. It returns several universities located within this area, including:
+    >
+    > - **University of Washington** in King County, Washington State, USA  
+    > - **University of Waterloo** in Waterloo, Ontario, Canada  
+    > - **University of Wyoming** in Laramie, Wyoming, USA  
+    > - **University of Windsor** in Windsor, Ontario, Canada  
+    > - **University of West Florida** in Escambia County, Florida, USA
+
+Next, narrow down the area included in your search to the United States, using the `countryRegion` parameter.
+
+1. Open the [Bruno] application.
+
+1. Select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
+
+1. Select the **GET** HTTP method in the **URL** drop-down list, then enter the following URL:
+
+    ```http
+    https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=university of w&bbox=-168,-52,5,84&countryRegion=us&subscription-key={Your-Azure-Maps-Subscription-key}
+    ```
+
+1. Select the run button, then review the response body.
+
+   > [!NOTE]
+    > The `bbox` parameter in the URL defines the same bounding box as in the previous example, however the `countryRegion=us` parameter limits results to the United States. It returns several universities located within this area, including:
+    >
+    > - **University of Washington** in King County, Washington State, USA
+    > - **University of Wyoming** in Laramie, Wyoming, USA
+    > - **University of West Florida** in Escambia County, Florida, USA
+    > - **University of Wisconsin-Superior** in Douglas County, Wisconsin, USA
+    > - **University of Wisconsin-Stout** in Menomonie, Dunn County, Wisconsin, USA
+
+Next, focus your search to include more results in a specific area within the defined `countryRegion`, using the `coordinates` parameter. This results in more items returned near the specified area that would otherwise not make the list.
+
+1. Open the [Bruno] application.
+
+1. Select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
+
+1. Select the **GET** HTTP method in the **URL** drop-down list, then enter the following URL:
+
+    ```http
+    https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=university of w&bbox=-168,-52,5,84&countryRegion=us&coordinates=-122.136791,47.642232&subscription-key={Your-Azure-Maps-Subscription-key}
+    ```
+
+1. Select the run button, then review the response body.
+
+   > [!NOTE]
+    > The `bbox` and `countryRegion` parameters in this URL define the same boundaries as in the previous example, however the `coordinates=-122.136791,47.642232` parameter focuses the search results to the specified area. It returns a local university that would otherwise not be returned.
+    >
+    > - **University of Washington** in King County, Washington State, USA
+    > - **University of Washington, Tacoma** in Tacoma, Pierce County, Washington State, USA
+    > - **University of Wyoming** in Laramie, Wyoming, USA
+    > - **University of West Florida** in Escambia County, Florida, USA
+    > - **University of Wisconsin-Stout** in Menomonie, Dunn County, Wisconsin, USA
+
+## Search for a street address using Get Reverse Geocoding
+
+[Get Reverse Geocoding] translates coordinates into human readable street addresses. This API is often used for applications that consume GPS feeds and want to discover addresses at specific coordinate points.
+
+> [!IMPORTANT]
+> To [geobias] results to the relevant area for your users, always add as many location details as possible. For more information, see [Best Practices for Search].
+
+> [!TIP]
+> If you have a set of coordinate locations to reverse geocode, you can use [Get Reverse Geocoding Batch] to send a batch of queries in a single request.
+
+This example demonstrates making reverse searches using a few of the optional parameters that are available. For the full list of optional parameters, see [Get Reverse Geocoding Parameters].
+
+1. Open the [Bruno] application.
+
+1. Select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
+
+1. Select the **GET** HTTP method in the **URL** drop-down list, then enter the following URL:
+
+    ```http
+    https://atlas.microsoft.com/reverseGeocode?api-version=2025-01-01&subscription-key={Your-Azure-Maps-Subscription-key}&coordinates=-122.332700,47.591180
+    ```
+
+1. Select the run button, and review the response body. You should see one query result. The response includes key address information about T-Mobile Park.
+  
+1. Next, add the following parameter to the request: `resultTypes=Postcode1`
+
+    ```http
+    https://atlas.microsoft.com/reverseGeocode?api-version=2025-01-01&subscription-key={Your-Azure-Maps-Subscription-key}&coordinates=-122.332700,47.591180&resultTypes=Postcode1
+    ```
+
+1. Select the run button, and compare the results to the results returned previously. Because the requested result type is now `Postcode1`, the response doesn't include street address information, just the zip code.
+
+## Search for cross street using Get Reverse Geocoding
+
+This example demonstrates how to search for a cross street based on the coordinates of an address.
+
+1. Open the [Bruno] application.
+
+1. Select **NEW REQUEST** to create the request. In the **NEW REQUEST** window, set **Type** to **HTTP**. Enter a **Name** for the request.
+
+1. Select the **GET** HTTP method in the **URL** drop-down list, then enter the following URL:
+  
+    ```http
+    https://atlas.microsoft.com/reverseGeocode?api-version=2025-01-01&coordinates=-122.12429011774091,47.61697905124655&subscription-key={Your-Azure-Maps-Subscription-key}
+    ```
+
+1. Select the run button, and review the response body.
+
+   The response includes an `intersection` section that identifies the street portion of the returned address: *NE 8th St*. It also specifies the intersecting street: *164th Ave NE*, and provides the full cross street as: *NE 8th St and 164th Ave NE*.
+
+   ```json
+    "intersection": {
+    "baseStreet": "NE 8th St",
+    "displayName": "NE 8th St and 164th Ave NE",
+    "intersectionType": "Near",
+    "secondaryStreet1": "164th Ave NE"
+    }
+   ```
+
+:::zone-end
+
 ## Next steps
 
 > [!div class="nextstepaction"]
@@ -176,6 +375,7 @@ This example demonstrates how to search for a cross street based on the coordina
 > [!div class="nextstepaction"]
 > [Best practices for Azure Maps Search service]
 
+[Get Geocode Autocomplete]: /rest/api/maps/search/get-geocode-autocomplete
 [Azure Maps account]: quick-demo-map-app.md#create-an-azure-maps-account
 [Azure Maps Search service]: /rest/api/maps/search?view=rest-maps-1.0&preserve-view=true
 [Best practices for Azure Maps Search service]: how-to-use-best-practices-for-search.md
@@ -184,6 +384,11 @@ This example demonstrates how to search for a cross street based on the coordina
 [Fuzzy Search URI Parameters]: /rest/api/maps/search/getsearchfuzzy?view=rest-maps-1.0&preserve-view=true#uri-parameters
 [Fuzzy Search]: /rest/api/maps/search/getsearchfuzzy?view=rest-maps-1.0&preserve-view=true
 [geobias]: glossary.md#geobias
+[Get Geocoding]: /rest/api/maps/search/get-geocoding
+[Get Geocoding Batch]: /rest/api/maps/search/get-geocoding-batch
+[Get Reverse Geocoding]: /rest/api/maps/search/get-reverse-geocoding
+[Get Reverse Geocoding Parameters]: /rest/api/maps/search/get-reverse-geocoding#uri-parameters
+[Get Reverse Geocoding Batch]: /rest/api/maps/search/get-reverse-geocoding-batch
 [Get Search Address Reverse]: /rest/api/maps/search/getsearchaddressreverse?view=rest-maps-1.0&preserve-view=true
 [Get Search Address]: /rest/api/maps/search/getsearchaddress?view=rest-maps-1.0&preserve-view=true
 [point of interest]: /rest/api/maps/search/getsearchpoi?view=rest-maps-1.0&preserve-view=true#searchpoiresponse