本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 如何使用 SearchNearby
本節包含各種如何使用 SearchNearby 的指南和範例。
**Topics**
+ [如何從位置搜尋附近的](how-to-search-nearby.md)
+ [如何根據類別搜尋附近的位置](how-to-search-nearby-category.md)
+ [如何根據食物類型搜尋附近的位置](how-to-search-nearby-food.md)
+ [如何根據業務鏈搜尋附近的](how-to-search-nearby-business.md)
+ [如何在某個國家/地區內搜尋附近](how-to-search-nearby-country.md)
+ [如何使用地理空間內容搜尋附近的](how-to-search-nearby-geospatial.md)
# 如何從位置搜尋附近的
SearchNearby API 可讓您查詢所有附近的位置和興趣點 (POI)，而無需輸入任何特定文字。使用者可以使用此 API 探索鄰里、探索 POIs等。它需要 `QueryPosition`，它可以代表裝置的位置、IP 型位置或地圖檢視區中心。或者，使用者可以根據該位置的地理座標，指定要偏差結果的城市或位置。
## 潛在的使用案例
+ **探索附近的 POIs：**檢視目前位置附近的所有興趣點。
+ **探索附近的位置：**檢視指定位置附近的所有位置。
## 範例
### 從位置搜尋附近的
在此範例中，搜尋是從位於杜拜的緯度 25.26951 和經度 55.30884 位置進行。
------
#### [ Sample request ]
```
{
"QueryPosition": [
55.30884,
25.26951
]
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointOfInterest",
"Title": "هما",
"Address": {
"Label": "هما, شارع مستشفى آل مكتوم, نايف دبي, الإمارات العربية المتحدة",
"Country": {
"Code2": "AE",
"Code3": "ARE",
"Name": "الإمارات العربية المتحدة"
},
"SubRegion": {
"Name": "دبي"
},
"Locality": "دبي",
"District": "نايف",
"Street": "شارع مستشفى آل مكتوم",
"StreetComponents": [
{
"BaseName": "مستشفى آل مكتوم",
"Type": "شارع",
"TypePlacement": "BeforeBaseName",
"TypeSeparator": " ",
"Language": "ar"
}
]
},
"Position": [
55.30884,
25.26951
],
"Distance": 0,
"Categories": [
{
"Id": "department_store",
"Name": "Department Store",
"LocalizedName": "مول تجاري",
"Primary": true
}
],
"BusinessChains": [
{
"Name": "HEMA",
"Id": "HEMA"
}
]
},
{
"PlaceId": "",
"PlaceType": "Locality",
"Title": "دبي, الإمارات العربية المتحدة",
"Address": {
"Label": "دبي, الإمارات العربية المتحدة",
"Country": {
"Code2": "AE",
"Code3": "ARE",
"Name": "الإمارات العربية المتحدة"
},
"SubRegion": {
"Name": "دبي"
},
"Locality": "دبي"
},
"Position": [
55.30884,
25.26951
],
"Distance": 0,
"MapView": [
54.64906,
24.62308,
55.7371,
25.36995
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
55.30884,
25.26951
],
"MaxResults": 2
}'
```
------
#### [ AWS CLI ]
```
aws geo-places search-nearby --key ${YourKey} \
--query-position 55.30884 25.26951 \
--max-results 2
```
------
# 如何根據類別搜尋附近的位置
SearchNearby API 可讓您查詢包含或排除指定類別的興趣點 (POI)。這可協助使用者探索鄰里、探索本機 POIs等。API 需要 `QueryPosition`，其可以根據裝置的位置、IP 位置或地圖檢視區的中心。或者，使用者可以指定城市或位置，應用程式會根據該位置的座標偏差結果。
若要進一步了解支援的類別，請參閱 [類別篩選條件](places-filtering.md#place-categories)。
## 潛在的使用案例
+ **探索本機設施：**尋找附近的可用設施。
+ **探索旅遊景點：**識別城市內的旅遊點。
+ **在城市規劃行程：**整理所選城市中不同 POIs周圍的行程。
## 範例
### 包含類別
------
#### [ Sample request ]
```
{
"QueryPosition": [
4.35609,
50.84439
],
"Filter": {
"IncludeCategories": ["airport"]
}
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointOfInterest",
"Title": "Brussels Airport",
"Address": {
"Label": "Brussels Airport, A201, 1930 Zaventem, België",
"Country": {
"Code2": "BE",
"Code3": "BEL",
"Name": "België"
},
"Region": {
"Code": "VLG",
"Name": "Vlaanderen"
},
"SubRegion": {
"Name": "Vlaams Brabant"
},
"Locality": "Zaventem",
"PostalCode": "1930",
"Street": "A201",
"StreetComponents": [
{
"BaseName": "A201",
"Language": "nl"
}
]
},
"Position": [
4.47767,
50.89452
],
"Distance": 10191,
"Categories": [
{
"Id": "airport",
"Name": "Airport",
"LocalizedName": "Luchthaven",
"Primary": true
}
]
},
{
"PlaceId": "",
"PlaceType": "PointOfInterest",
"Title": "Internationale Luchthaven Antwerpen",
"Address": {
"Label": "Internationale Luchthaven Antwerpen, Luchthavenlei 1, 2100 Antwerpen, België",
"Country": {
"Code2": "BE",
"Code3": "BEL",
"Name": "België"
},
"Region": {
"Code": "VLG",
"Name": "Vlaanderen"
},
"SubRegion": {
"Name": "Antwerpen"
},
"Locality": "Antwerpen",
"District": "Deurne",
"PostalCode": "2100",
"Street": "Luchthavenlei",
"StreetComponents": [
{
"BaseName": "Luchthaven",
"Type": "lei",
"TypePlacement": "AfterBaseName",
"TypeSeparator": "",
"Language": "nl"
}
],
"AddressNumber": "1"
},
"Position": [
4.45083,
51.18867
],
"Distance": 38852,
"Categories": [
{
"Id": "airport",
"Name": "Airport",
"LocalizedName": "Luchthaven",
"Primary": true
}
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
4.35609,
50.84439
],
"Filter": {
"IncludeCategories": ["airport"]
},
"MaxResults": 2
}
```
------
#### [ AWS CLI ]
```
aws geo-places search-nearby --key ${YourKey} \
--query-position 4.35609 50.84439 \
--filter '{"IncludeCategories": ["airport"]}' \
--max-results 2
```
------
### 排除類別
------
#### [ Sample request ]
```
{
"QueryPosition": [
4.35609,
50.84439
],
"Filter": {
"ExcludeCategories": ["airport"]
}
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointOfInterest",
"Title": "Socialbrands Module 2",
"Address": {
"Label": "Socialbrands Module 2, Albertinaplein, 1000 Brussel, België",
"Country": {
"Code2": "BE",
"Code3": "BEL",
"Name": "België"
},
"Region": {
"Code": "BRU",
"Name": "Brussel"
},
"SubRegion": {
"Name": "Brussel"
},
"Locality": "Brussel",
"District": "Koningswijk",
"PostalCode": "1000",
"Street": "Albertinaplein",
"StreetComponents": [
{
"BaseName": "Albertina",
"Type": "plein",
"TypePlacement": "AfterBaseName",
"TypeSeparator": "",
"Language": "nl"
}
]
},
"Position": [
4.35609,
50.84439
],
"Distance": 0,
"Categories": [
{
"Id": "commercial_services",
"Name": "Commercial Services",
"LocalizedName": "Commerciële diensten",
"Primary": true
}
],
"Contacts": {
"Websites": [
{
"Value": "https://oneread.net"
}
]
},
"AccessPoints": [
{
"Position": [
4.35609,
50.84439
]
}
]
},
{
"PlaceId": "",
"PlaceType": "PointOfInterest",
"Title": "Barman Privé",
"Address": {
"Label": "Barman Privé, Albertinaplein, 1000 Brussel, België",
"Country": {
"Code2": "BE",
"Code3": "BEL",
"Name": "België"
},
"Region": {
"Code": "BRU",
"Name": "Brussel"
},
"SubRegion": {
"Name": "Brussel"
},
"Locality": "Brussel",
"District": "Koningswijk",
"PostalCode": "1000",
"Street": "Albertinaplein",
"StreetComponents": [
{
"BaseName": "Albertina",
"Type": "plein",
"TypePlacement": "AfterBaseName",
"TypeSeparator": "",
"Language": "nl"
}
]
},
"Position": [
4.35609,
50.84439
],
"Distance": 0,
"Categories": [
{
"Id": "catering_and_other_food_services",
"Name": "Catering and Other Food Services",
"LocalizedName": "Catering- en horecadiensten",
"Primary": true
}
],
"Contacts": {
"Phones": [
{
"Value": "+32476891634"
}
]
},
"OpeningHours": [
{
"Display": [
"ma-zo: 00:00 - 24:00"
],
"OpenNow": true,
"Components": [
{
"OpenTime": "T000000",
"OpenDuration": "PT24H00M",
"Recurrence": "FREQ:DAILY;BYDAY:MO,TU,WE,TH,FR,SA,SU"
}
]
}
],
"AccessPoints": [
{
"Position": [
4.35609,
50.84439
]
}
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
4.35609,
50.84439
],
"Filter": {
"ExcludeCategories": ["airport"]
}
}
```
------
#### [ AWS CLI ]
```
aws geo-places search-nearby --key ${YourKey} \
--query-position 4.35609 50.84439 \
--filter '{"ExcludeCategories": ["airport"]}' \
--max-results 2
```
------
# 如何根據食物類型搜尋附近的位置
`SearchNearby` API 可讓您查詢提供特定類型食物的附近餐廳。您也可以從結果中排除食品類型。
您可以使用 SearchNearby API，讓使用者探索鄰里並探索感興趣的位置。API 需要 QueryPosition，可以是裝置位置、IP 位置或地圖的檢視連接埠中心。另一種方法是讓最終使用者提供城市名稱或位置名稱，而應用程式可以根據地理座標偏差結果。
如需食品類型的詳細資訊，請參閱 [食品類型篩選條件](places-filtering.md#food-type)。
## 潛在的使用案例
+ 探索附近可用的食物類型。
+ 排除提供讓您敏感之食品類型的餐廳選項。
## 範例
### 依食物類型搜尋附近的位置
下列範例示範如何根據食物類型搜尋附近的位置。
------
#### [ Sample request ]
此請求會搜尋在指定座標附近提供中式食品餐廳。
```
{
"QueryPosition": [
12.49563,
41.90325
],
"Filter": {
"IncludeFoodTypes": ["chinese"]
}
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointOfInterest",
"Title": "Bufala e Pachino",
"Address": {
"Label": "Bufala e Pachino, Via Firenze, 53, 00184 Roma RM, Italia",
"Country": {
"Code2": "IT",
"Code3": "ITA",
"Name": "Italia"
}
},
"Position": [
12.49409,
41.90237
],
"Distance": 161,
"Categories": [
{
"Id": "restaurant",
"Name": "Restaurant",
"LocalizedName": "Ristorante",
"Primary": true
}
],
"FoodTypes": [
{
"LocalizedName": "Pizza",
"Id": "pizza",
"Primary": true
},
{
"LocalizedName": "Cinese",
"Id": "chinese",
"Primary": false
}
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [12.49563, 41.90325],
"Filter": {
"IncludeFoodTypes": ["chinese"]
}
}'
```
------
#### [ AWS CLI ]
```
aws geo-places search-nearby --key ${YourKey} \
--query-position 12.49563 41.90325 \
--filter '{"IncludeFoodTypes": ["chinese"]}'
```
------
### 開發人員秘訣
+ 您可以使用 `ExludeFoodTypes` 從結果中排除某些業務鏈。
+ 您可以排除或包含多種食物類型。
# 如何根據業務鏈搜尋附近的
SearchNearby API 可讓您查詢附近的商業鏈。您可以在搜尋中包含或排除特定業務鏈。此功能可讓最終使用者探索鄰里、探索興趣點等。
若要使用 SearchNearby API，您需要提供 QueryPosition，其可以是：
+ 裝置位置
+ IP 型位置
+ 地圖的檢視區中心
或者，使用者可以提供城市名稱或位置，而應用程式可以根據該位置的地理座標來偏差結果。
如需支援的業務鏈詳細資訊，請參閱 [Business Chains 篩選條件](places-filtering.md#business-chains)。
## 潛在的使用案例
+ 探索附近的企業
+ 透過尋找附近的 B2B 客戶來擴展您的業務
## 範例
### 依業務鏈搜尋附近的位置
下列範例示範如何搜尋附近的 Starbucks 位置。
------
#### [ Sample request ]
此請求會搜尋指定座標附近的 Starbucks 位置。
```
{
"QueryPosition": [
12.49563,
41.90325
],
"Filter" : {
"IncludeBusinessChains": ["Starbucks"]
}
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointOfInterest",
"Title": "Starbucks",
"Address": {
"Label": "Starbucks, Via Giovanni Giolitti, 2, 00185 Roma RM, Italia",
"Country": {
"Code2": "IT",
"Code3": "ITA",
"Name": "Italia"
},
"Region": {
"Name": "Lazio"
},
"SubRegion": {
"Code": "RM",
"Name": "Roma"
},
"Locality": "Roma",
"District": "Esquilino",
"PostalCode": "00185",
"Street": "Via Giovanni Giolitti",
"StreetComponents": [
{
"BaseName": "Giovanni Giolitti",
"Type": "Via",
"TypePlacement": "BeforeBaseName",
"TypeSeparator": " ",
"Language": "it"
}
],
"AddressNumber": "2"
},
"Position": [
12.50102,
41.90093
],
"Distance": 515,
"Categories": [
{
"Id": "coffee_shop",
"Name": "Coffee Shop",
"LocalizedName": "Bar",
"Primary": true
}
],
"BusinessChains": [
{
"Name": "Starbucks",
"Id": "Starbucks"
}
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
12.49563,
41.90325
],
"Filter" : {
"IncludeBusinessChains": ["Starbucks"]
}
}'
```
------
#### [ AWS CLI ]
```
aws geo-places search-nearby --key ${YourKey} \
--query-position 12.49563 41.90325 \
--filter '{"IncludeBusinessChains": ["Starbucks"]}'
```
------
## 開發人員秘訣
+ 您可以使用 `ExcludeBusinessChains` 從結果中排除某些業務鏈。
+ 您可以排除或包含多個業務鏈。
# 如何在某個國家/地區內搜尋附近
SearchNearby API 可讓您搜尋特定國家/地區的附近位置。若要使用 API，您需要提供 QueryPosition，可以是：
+ 裝置位置
+ IP 型位置
+ 地圖的檢視區中心
或者，使用者可以提供城市名稱或位置，而應用程式可以根據該位置的地理座標偏差結果。
## 潛在的使用案例
+ 探索某個國家/地區的企業
+ 尋找國家/地區內附近的 B2B 客戶
+ 探索某個國家/地區的旅遊地點
## 範例
### 搜尋加拿大的球場
下列範例示範如何搜尋加拿大境內靠近指定座標的課程。
------
#### [ Sample request ]
此請求會在指定的位置附近搜尋加拿大的球場。
```
{
"QueryPosition": [
-122.741803,
49.002478
],
"Filter" : {
"IncludeCategories": ["golf_course"],
"IncludeCountries": ["CAN"]
}
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointOfInterest",
"Title": "Peace Portal Golf Course",
"Address": {
"Label": "Peace Portal Golf Course, 16900 * Ave, Surrey, BC V*Z *P*, Canada",
"Country": {
"Code2": "CA",
"Code3": "CAN",
"Name": "Canada"
},
"Region": {
"Code": "BC",
"Name": "British Columbia"
},
"SubRegion": {
"Name": "Metro Vancouver"
},
"Locality": "Surrey",
"District": "South Surrey",
"PostalCode": "V*Z *P*",
"Street": "* Ave",
"StreetComponents": [
{
"BaseName": "4",
"Type": "Ave",
"TypePlacement": "AfterBaseName",
"TypeSeparator": " ",
"Language": "en"
}
],
"AddressNumber": "16900"
},
"Position": [
-122.75086,
49.00921
],
"Distance": 998,
"Categories": [
{
"Id": "golf_course",
"Name": "Golf Course",
"LocalizedName": "Golf Course",
"Primary": true
}
],
"Contacts": {
"Phones": [
{
"Value": "+16045384818" }
],
"Websites": [
{
"Value": "http://www.peaceportalgolf.com"
}
]
},
"AccessPoints": [
{
"Position": [
-122.75087,
49.00935
]
}
]
}
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
-122.741803,
49.002478
],
"Filter" : {
"IncludeCategories": ["golf_course"],
"IncludeCountries": ["CAN"]
}
}'
```
------
#### [ AWS CLI ]
```
aws geo-places search-nearby --key ${YourKey} \
--query-position -122.741803 49.002478 \
--filter '{"IncludeCategories": ["golf_course"], "IncludeCountries": ["CAN"]}'
```
------
# 如何使用地理空間內容搜尋附近的
SearchNearby API 可讓您探索附近，同時限制地理空間內容 （例如圓圈或週框方塊） 內的結果。
SearchNearby API 可讓您使用地理空間內容篩選結果，例如圓圈和週框方塊。透過定義這些地理邊界，您可以將搜尋結果限制在特定區域。
## 潛在的使用案例
+ 將搜尋結果限制在特定地理區域
+ 在自訂定義的邊界內搜尋
+ 將結果集中在目標鄰里或區域
## 範例
### 使用查詢半徑搜尋
下列範例示範如何搜尋指定座標 1000 公尺半徑內的學校。
------
#### [ Sample request ]
此請求會搜尋 1000 公尺 (1 公里） 半徑內的學校。
```
{
"QueryPosition": [
-122.741803,
49.002478
],
"QueryRadius":1000,
"Filter" : {
"IncludeCategories": ["school"]
}
}
```
------
#### [ Sample response ]
```
{
"ResultItems": [
{
"PlaceId": "",
"PlaceType": "PointOfInterest",
"Title": "Grace Lutheran Church",
"Address": {
"Label": "Grace Lutheran Church, 702 G St, Blaine, WA 98230-5125, United States",
"Country": {
"Code2": "US",
"Code3": "USA",
"Name": "United States"
},
"Region": {
"Code": "WA",
"Name": "Washington"
},
"SubRegion": {
"Name": "Whatcom"
},
"Locality": "Blaine",
"PostalCode": "98230-5125",
"Street": "G St",
"StreetComponents": [
{
"BaseName": "G",
"Type": "St",
"TypePlacement": "AfterBaseName",
"TypeSeparator": " ",
"Language": "en"
}
],
"AddressNumber": "702"
},
"Position": [
-122.74157,
48.99533
],
"Distance": 795,
"Categories": [
{
"Id": "church",
"Name": "Church",
"LocalizedName": "Church",
"Primary": true
},
{
"Id": "kindergarten_and_childcare",
"Name": "Kindergarten and Childcare",
"LocalizedName": "Kindergarten & Childcare",
"Primary": false
},
{
"Id": "school",
"Name": "School",
"LocalizedName": "School",
"Primary": false
}
]
}
...
]
}
```
------
#### [ cURL ]
```
curl --request POST \
--url 'https://places.geo.eu-central-1.amazonaws.com/v2/search-nearby?key=Your_Key' \
--header 'Content-Type: application/json' \
--data '{
"QueryPosition": [
-122.741803,
49.002478
],
"QueryRadius": 1000,
"Filter": {
"IncludeCategories": ["school"]
}
}'
```
------
#### [ AWS CLI ]
```
aws geo-places search-nearby --key ${YourKey} \
--query-position -122.741803 49.002478 \
--query-radius 1000 \
--filter '{"IncludeCategories": ["school"]}'
```
------
## 開發人員秘訣
+ 或者，您可以使用週框方塊篩選條件。