You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/azure-maps/how-to-search-for-address.md
+59-57Lines changed: 59 additions & 57 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,12 +14,12 @@ services: azure-maps
14
14
15
15
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] services.
16
16
17
-
In this article, you'll learn how to:
17
+
This article demonstrates how to:
18
18
19
19
* Request latitude and longitude coordinates for an address (geocode address location) by using [Search Address].
20
20
* Search for an address or Point of Interest (POI) using [Fuzzy Search].
21
21
* Use [Reverse Address Search] to translate coordinate location to street address.
22
-
* Translate coordinate location into a human understandable cross street using [Search Address Reverse Cross Street]. Most often, this is needed in tracking applications that receive a GPS feed from a device or asset, and wish to know where the coordinate is located.
22
+
* 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.
23
23
24
24
## Prerequisites
25
25
@@ -30,7 +30,7 @@ This tutorial uses the [Postman] application, but you may choose a different API
30
30
31
31
## Request latitude and longitude for an address (geocoding)
32
32
33
-
In this example, we'll use [Get Search Address] to convert an address into latitude and longitude coordinates. This process is also called *geocoding*. In addition to returning the coordinates, the response will also return detailed address properties such as street, postal code, municipality, and country/region information.
33
+
The example in this section uses [Get Search Address] 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.
34
34
35
35
>[!TIP]
36
36
>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.
@@ -43,29 +43,29 @@ In this example, we'll use [Get Search Address] to convert an address into latit
43
43
https://atlas.microsoft.com/search/address/json?&subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&language=en-US&query=400 Broad St, Seattle, WA 98109
44
44
```
45
45
46
-
3. Click the blue **Send** button. The response body will contain data for a single location.
46
+
3. Select the blue **Send** button. The response body contains data for a single location.
47
47
48
-
4. Now, we'll search an address that has more than one possible locations. In the **Params** section, change the `query` key to `400 Broad, Seattle`. Click the blue **Send** button.
48
+
4. Next, search an address that has more than one possible locations. In the **Params** section, change the `query` key to `400 Broad, Seattle`. Select the blue **Send** button.
49
49
50
50
:::image type="content" source="./media/how-to-search-for-address/search-address.png" alt-text="Search for address":::
51
51
52
52
5. Next, try setting the `query` key to `400 Broa`.
53
53
54
-
6. Click the **Send** button. You can now see that the response includes responses from multiple countries. To geobias results to the relevant area for your users, always add as many location details as possible to the request.
54
+
6. Select the **Send** button. The response includes results from multiple countries. To geobias results to the relevant area for your users, always add as many location details as possible to the request.
55
55
56
56
## Fuzzy Search
57
57
58
-
[Fuzzy Search] supports standard single line and free-form searches. We recommend that you use the Azure Maps Search Fuzzy API when you don't know your user input type for a search request. The query input can be a full or partial address. It can also be a Point of Interest (POI) token, like a name of POI, POI category or name of brand. Furthermore, to improve the relevance of your search results, the query results can be constrained by a coordinate location and radius, or by defining a bounding box.
58
+
[Fuzzy Search] supports standard single line and free-form searches. We recommend that you use the Azure Maps Search Fuzzy API when you don't know your user input type for a search request. The query input can be a full or partial address. It can also be a Point of Interest (POI) token, like a name of POI, POI category or name of brand. Furthermore, to improve the relevance of your search results, constrain the query results using a coordinate location and radius, or by defining a bounding box.
59
59
60
-
>[!TIP]
61
-
>Most Search queries default to maxFuzzyLevel=1 to gain performance and reduce unusual results. You can adjust fuzziness levels by using the `maxFuzzyLevel` or `minFuzzyLevel` parameters. For more information on `maxFuzzyLevel` and a complete list of all optional parameters, see [Fuzzy Search URI Parameters].
60
+
>[!TIP]
61
+
>Most Search queries default to `maxFuzzyLevel=1` to improve performance and reduce unusual results. Adjust fuzziness levels by using the `maxFuzzyLevel` or `minFuzzyLevel` parameters. For more information on `maxFuzzyLevel` and a complete list of all optional parameters, see [Fuzzy Search URI Parameters].
62
62
63
63
### Search for an address using Fuzzy Search
64
64
65
-
In this example, we'll use Fuzzy Search to search the entire world for `pizza`. Then, we'll show you how to search over the scope of a specific country. Finally, we'll show you how to use a coordinate location and radius to scope a search over a specific area, and limit the number of returned results.
65
+
The example in this section uses `Fuzzy Search` to search the entire world for *pizza*, then searches over the scope of a specific country. Finally, it demonstrates how to use a coordinate location and radius to scope a search over a specific area, and limit the number of returned results.
66
66
67
-
>[!IMPORTANT]
68
-
>To geobias results to the relevant area for your users, always add as many location details as possible. To learn more, see [Best Practices for Search].
67
+
>[!IMPORTANT]
68
+
>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].
69
69
70
70
1. In the Postman app, select **New** to create the request. In the **Create New** window, select **HTTP Request**. Enter a **Request name** for the request.
71
71
@@ -75,45 +75,45 @@ In this example, we'll use Fuzzy Search to search the entire world for `pizza`.
>The _json_ attribute in the URL path determines the response format. This article uses json for ease of use and readability. To find other supported response formats, see the `format` parameter definition in the [URI Parameter reference] documentation.
78
+
>[!NOTE]
79
+
>The _json_ attribute in the URL path determines the response format. This article uses json for ease of use and readability. To find other supported response formats, see the `format` parameter definition in the [URI Parameter reference] documentation.
80
80
81
-
3. Click **Send** and review the response body.
81
+
3. Select **Send** and review the response body.
82
82
83
-
The ambiguous query string for "pizza" returned 10 [point of interest result] (POI) in both the "pizza" and "restaurant" categories. Each result includes details such as street address, latitude and longitude values, view port, and entry points for the location. The results are now varied for this query, and are not tied to any reference location.
83
+
The ambiguous query string for "pizza" returned 10 [point of interest result] (POI) in both the "pizza" and "restaurant" categories. Each result includes details such as street address, latitude and longitude values, view port, and entry points for the location. The results are now varied for this query, and aren't tied to any reference location.
84
84
85
-
In the next step, we'll use the `countrySet` parameter to specify only the countries/regions for which your application needs coverage. For a complete list of supported countries/regions, see [Search Coverage].
85
+
In the next step, you'll use the `countrySet` parameter to specify only the countries/regions for which your application needs coverage. For a complete list of supported countries/regions, see [Search Coverage].
86
86
87
-
4. The default behavior is to search the entire world, potentially returning unnecessary results. Next, we’ll search for pizza only the United States. Add the `countrySet` key to the **Params** section, and set its value to `US`. Setting the `countrySet` key to `US` will bound the results to the United States.
87
+
4. The default behavior is to search the entire world, potentially returning unnecessary results. Next, search for pizza only in the United States. Add the `countrySet` key to the **Params** section, and set its value to `US`. Setting the `countrySet` key to `US` bounds the results to the United States.
88
88
89
89
:::image type="content" source="./media/how-to-search-for-address/search-fuzzy-country.png" alt-text="Search for pizza in the United States":::
90
90
91
91
The results are now bounded by the country code and the query returns pizza restaurants in the United States.
92
92
93
-
5. To get an even more targeted search, you can search over the scope of a lat./lon. coordinate pair. In this example, we'll use the lat./lon. of the Seattle Space Needle. Since we only want to return results within a 400-meters radius, we'll add the `radius` parameter. Also, we'll add the `limit` parameter to limit the results to the five closest pizza places.
93
+
5. To get an even more targeted search, you can search over the scope of a lat/lon coordinate pair. The following example uses the lat/lon coordinates of the Seattle Space Needle. Since we only want to return results within a 400-meters radius, weadd the `radius` parameter. Also, we add the `limit` parameter to limit the results to the five closest pizza places.
94
94
95
95
In the **Params** section, add the following key/value pairs:
96
96
97
-
| Key | Value |
98
-
|-----|------------|
99
-
| lat | 47.620525 |
100
-
| lon | -122.349274|
101
-
| radius | 400 |
102
-
| limit | 5|
97
+
| Key | Value |
98
+
|--------|------------|
99
+
| lat | 47.620525 |
100
+
| lon | -122.349274|
101
+
| radius | 400 |
102
+
| limit | 5|
103
103
104
-
6. Click **Send**. The response includes results for pizza restaurants near the Seattle Space Needle.
104
+
6. Select **Send**. The response includes results for pizza restaurants near the Seattle Space Needle.
105
105
106
106
## Search for a street address using Reverse Address Search
107
107
108
108
[Get Search Address Reverse] 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.
109
109
110
-
>[!IMPORTANT]
111
-
>To geobias results to the relevant area for your users, always add as many location details as possible. To learn more, see [Best Practices for Search].
110
+
>[!IMPORTANT]
111
+
>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].
112
112
113
-
>[!TIP]
114
-
>If you have a set of coordinate locations to reverse geocode, you can use [Post Search Address Reverse Batch] to send a batch of queries in a single request.
113
+
>[!TIP]
114
+
>If you have a set of coordinate locations to reverse geocode, you can use [Post Search Address Reverse Batch] to send a batch of queries in a single request.
115
115
116
-
In this example, we'll be making reverse searches using a few of the optional parameters that are available. For the full list of optional parameters, see [Reverse Search Parameters].
116
+
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].
117
117
118
118
1. In the Postman app, select **New** to create the request. In the **Create New** window, select **HTTP Request**. Enter a **Request name** for the request.
119
119
@@ -123,9 +123,9 @@ In this example, we'll be making reverse searches using a few of the optional pa
6. Next, we'll add the `entityType` key, and set its value to `Municipality`. The `entityType` key will override the `returnMatchType` key in the previous step. We'll also need to remove `returnSpeedLimit` and `returnRoadUse` since we're requesting information about the municipality. For all possible entity types, see [Entity Types].
141
+
6. Next, we 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].
7. Click **Send**. Compare the results to the results returned in step 5. Because the requested entity type is now `municipality`, the response does not include street address information. Also, the returned `geometryId` can be used to request boundary polygon through Azure Maps Get [Search Polygon API].
145
+
7. Select **Send**. 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].
146
146
147
-
>[!TIP]
148
-
>To get more information on these parameters, as well as to learn about others, see [Reverse Search Parameters].
147
+
>[!TIP]
148
+
> For more information on these as well as other parameters, see [Reverse Search Parameters].
149
149
150
150
## Search for cross street using Reverse Address Cross Street Search
151
151
152
-
In this example, we'll search for a cross street based on the coordinates of an address.
152
+
This example demonstrates how to search for a cross street based on the coordinates of an address.
153
153
154
154
1. In the Postman app, select **New** to create the request. In the **Create New** window, select **HTTP Request**. Enter a **Request name** for the request.
155
155
@@ -161,37 +161,39 @@ In this example, we'll search for a cross street based on the coordinates of an
0 commit comments