本文說明如何將 Bing 地圖服務的依地址尋找位置 API 移轉至 Azure 地圖服務的取得地理編碼 API。 Azure 地圖服務的取得地理編碼 API 可用來取得街道地址、地點或地標的經度和緯度座標。 Azure 地圖服務的取得地理編碼 API 支援非結構化或結構化格式的地理編碼輸入。 本文說明地理編碼輸入 (例如街道地址) 採用結構化格式的案例 - 類似於 Bing 地圖服務的依地址尋找位置 API 所支援的案例。 若要了解如何移轉以非結構化格式的地理編碼輸入取得街道地址、地點或地標的經度和緯度座標的 Bing 地圖服務案例，請參閱移轉 Bing 地圖服務的依查詢尋找位置 API。
必要條件
- 一個 Azure 帳戶
- Azure 地圖服務帳戶
- 訂用帳戶金鑰或其他形式的 Azure 地圖服務驗證
需要注意的差異
- Bing 地圖服務的依地址尋找位置 API 僅支援結構化格式的地理編碼輸入，而 Azure 地圖服務的取得地理編碼 API 則支援非結構化 (query=) 或結構化 (addressLine=) 格式的地理編碼輸入。 針對地理編碼的地標名稱，請使用採用非結構化輸入格式的 Azure 地圖服務取得地理編碼 API。
- Bing 地圖服務的依地址尋找位置 API 會傳回緯度/經度格式的座標，而 Azure 地圖服務的取得地理編碼 API 則會以經度/緯度格式傳回座標，如 GeoJSON 格式所定義。
- Bing 地圖服務的依地址尋找位置 API 支援 XML 和 JSON 回應格式。 Azure 地圖服務的取得地理編碼 API 支援 GeoJSON。
- 不同於 Bing 地圖服務的依地址尋找位置 API，Azure 地圖服務的取得地理編碼 API 具有
view輸入參數，這是表示 ISO 3166-1 Alpha-2 區域碼/國碼的字串。view輸入參數會改變地緣政治爭議邊界和標籤，使其與指定的使用者區域保持一致。 如需詳細資訊，請參閱 URI 參數。 - 不同於 Bing 地圖服務的依地址尋找位置 API，Azure 地圖服務的取得地理編碼 API 目前不支援中國、日本或南韓的地址地理編碼。
- 不同於 Bing 地圖服務企業版，Azure 地圖服務是支援指定地理範圍的全域服務，可讓您將資料落地限制為歐洲 (EU) 或美國 (US) 地理區域 (地理位置)。 所有要求 (包括輸入資料) 都會以獨佔方式在指定的地理區域中處理。 如需詳細資訊，請參閱地理範圍。
安全性和驗證
Bing 地圖服務企業版僅支援 API 金鑰驗證。 Azure 地圖服務支援多種方式來驗證 API 呼叫，例如 訂用帳戶金鑰、Microsoft Entra ID，以及共用存取簽章 (SAS) 權杖。 如需 Azure 地圖服務 中安全性和驗證的詳細資訊，請參閱 Azure 地圖服務 取得地理編碼檔中的<使用 Azure 地圖服務 進行驗證>和一節。
要求參數
下表列出 Bing 地圖服務的依地址尋找位置要求參數和 Azure 地圖服務對等項目：
| Bing 地圖 要求參數 | Bing 地圖 要求參數別名 | Azure 地圖服務 要求參數 | Azure 地圖服務中需要 | Azure 地圖服務 數據類型 | 描述 |
|---|---|---|---|---|---|
| Bing 地圖 要求參數 | Bing 地圖 要求參數別名 | Azure 地圖服務 要求參數 | Azure 地圖服務中需要 | Azure 地圖服務 數據類型 | 附註 |
| addressLine | addressLine | False | 字串 | 在 Azure 地圖服務的取得地理編碼 API 中，支援為 addressLine 輸入街道地址，或具有地區和 adminDistrict 的街道地址。 |
|
| adminDistrict | adminDistrict | False | 字串 | ||
| countryRegion | countryRegion | False | 字串 | ||
| 地區 | 地區 | False | 字串 | ||
| postalCode | postalCode | False | 字串 | ||
| culture | c | 要求標頭：Accept-Language | False | 字串 | 如 Azure 地圖服務要求標頭中所指定，使用 Azure 地圖服務的取得地理編碼 API 時，culture 會定義搜尋結果中使用的語言。 如需詳細資訊，請參閱支援的語言。 |
| include | incl | 不需要 | 不需要 | 不需要 | 在 Bing 地圖服務的依地址尋找位置 API 中，需要 'include' 輸入參數才能取得回應中位置結果的雙字母 ISO 國碼/地區碼 (include=ciso2)。 在 Azure 地圖服務的取得地理編碼 API 中，依預設會傳回雙字母 ISO 國碼/地區碼。 |
| includeNeighborhood | inclnb | 不需要 | 不需要 | 不需要 | 在 Azure 地圖服務的取得地理編碼 API 中，依預設會在回應中傳回鄰近地區資訊 (如果適用)。 |
| maxResults | maxRes | top | False | 整數 (int32) | 在 Azure 地圖服務的取得地理編碼 API 中，依預設會傳回 5 個回應。 最小值為 1，最大值為 20。 |
| strictMatch | sm | 不支援 | 不支援 | 不支援 | |
| userIp | uip | 不支援 | 不支援 | 不支援 | |
| userLocation | ul | coordinates | False | number[] | 在 Azure 地圖服務的取得地理編碼 API 中，以經度和緯度格式 (longitude,latitude) 指定的地球上座標。 指定此參數時會考量使用者的位置，而傳回的結果會與使用者有更高的相關程度。 |
| userMapView | umv | bbox | False | number[] | 地球上的矩形區域，定義為週框方塊物件。 矩形的兩側是由經度和緯度值 (longitude1,latitude1,longitude2,latitude2) 所定義。 使用下列語法指定週框方塊：西經、南緯、東經、北緯 若指定此參數，計算位置查詢的結果時將會考量地理區域。 |
| userRegion | ur | 檢視 | False | 字串 | 一個表示 ISO 3166-1 Alpha-2 區域碼/國碼的字串，會改變地緣政治爭議邊界和標籤，使其與指定的使用者區域保持一致。 根據預設，「檢視」參數會設定為「自動」，即使未在要求中定義亦然。 如需可用檢視的詳細資訊，請參閱支援的檢視。 |
若要深入了解 Azure 地圖服務的取得地理編碼 API 要求參數，請參閱 URI 參數。
要求範例
Bing 地圖服務的依地址尋找位置 API POST 要求：
http://dev.virtualearth.net/REST/v1/Locations/US/WA/Redmond/15127 NE 24th Street?&key={BingMapsKey}
Azure 地圖服務的取得地理編碼 API POST 要求：
https://atlas.microsoft.com/geocode?api-version=2023-06-01&adminDistrict=WA&locality=Redmond&addressLine=15127 NE 24th Street&subscription-key={Your-Azure-Maps-Subscription-key}
回應欄位
下表列出在執行 Bing 地圖服務的依地址尋找位置要求和 Azure 地圖服務對等項目時，可在 HTTP 回應中顯示的欄位：
| Bing 地圖服務欄位 | Azure 地圖服務欄位 | 描述 |
|---|---|---|
| 地址：addressLine (JSON) 地址：AddressLine (XML) |
地址：addressLine | |
| 地址：adminDistrict (JSON) 地址：AdminDistrict (XML) |
地址：adminDistricts | |
| 地址：adminDistrict2 (JSON) 地址：AdminDistrict2 (XML) |
地址：adminDistricts | |
| 地址：countryRegion (JSON) 地址：CountryRegion (XML) |
地址：countryRegion | |
| 地址：countryRegionIso2 (JSON) 地址：CountryRegionIso2 (XML) |
地址：countryRegion - iso | |
| 地址：neighborhood (JSON) 地址：Neighborhood (XML) |
地址：neighborhood | |
| 地址：formattedAddress (JSON) 地址：FormattedAddress (XML) |
地址：formattedAddress | |
| 地址：locality (JSON) 地址：Locality (XML) |
地址：locality | |
| 地址：postalCode (JSON) 地址：PostalCode (XML) |
地址：postalCode | |
| 地址：Intersection – baseStreet (JSON) 地址：Intersection – BaseStreet (XML) |
地址：intersection -baseStreet | |
| 地址：Intersection – secondaryStreet1 (JSON) |
地址：intersection - secondaryStreet1 | |
| 地址：Intersection – secondaryStreet2 (JSON) 地址：Intersection – SecondaryStreet2 (XML) |
地址：intersection - secondaryStreet2 | |
| 地址：Intersection – intersectionType (JSON) 地址：Intersection – IntersectionType (XML) |
地址：intersection - intersectionType | |
| 地址：Intersection – displayName (JSON) 地址：Intersection – DisplayName (XML) |
地址：intersection - displayName | |
| bbox (JSON) BoundingBox (XML) |
特徵：bbox | 在 Bing 地圖服務的依地址尋找位置 API 中，回應中的座標會使用緯度/經度格式。 Azure 地圖服務的取得地理編碼 API 回應中的座標採用經度/緯度格式 (因為使用 GeoJSON 格式)。 |
| calculationMethod (JSON) CalculationMethod (XML) |
屬性：geocodePoints - calculationMethod | |
| confidence (JSON) Confidence (XML) |
屬性：confidence | |
| entityType (JSON) EntityType (XML) |
屬性：type | |
| geocodePoints (JSON) GeocodePoint (XML) |
屬性：geocodePoints - coordinates | |
| matchCodes (JSON) MatchCode (XML) |
屬性：matchCodes | |
| name (JSON) Name (XML) |
不支援 | formattedAddress 是 Azure 地圖服務對等項目。 |
| point (JSON) Point (XML) |
特徵：coordinates | 在 Bing 地圖服務的依地址尋找位置 API 中，回應中的座標會使用緯度/經度格式。 Azure 地圖服務的取得地理編碼 API 回應中的座標採用經度/緯度格式 (因為使用 GeoJSON 格式)。 |
| queryParse (JSON) QueryParse (XML) |
不支援 | |
| usageTypes (JSON) usageType (XML) |
屬性：geocodePoints: usageTypes |
如需 Azure 地圖服務的取得地理編碼 API 回應欄位的詳細資訊，請參閱定義。
回應範例
下列 JSON 範例顯示執行 Bing 地圖服務的依地址尋找位置要求時，HTTP 回應的本文中傳回的內容：
{
"authenticationResultCode": "ValidCredentials",
"brandLogoUri": "https://dev.virtualearth.net/Branding/logo_powered_by.png",
"copyright": "Copyright © 2024 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.",
"resourceSets": [
{
"estimatedTotal": 1,
"resources": [
{
"__type": "Location:http://schemas.microsoft.com/search/local/ws/rest/v1",
"bbox": [
47.62649628242932,
-122.14631082421619,
47.634221717570675,
-122.1310271757838
],
"name": "15127 NE 24th St, Redmond, WA 98052",
"point": {
"type": "Point",
"coordinates": [
47.630359,
-122.138669
]
},
"address": {
"addressLine": "15127 NE 24th St",
"adminDistrict": "WA",
"adminDistrict2": "King County",
"countryRegion": "United States",
"formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
"locality": "Redmond",
"postalCode": "98052"
},
"confidence": "High",
"entityType": "Address",
"geocodePoints": [
{
"type": "Point",
"coordinates": [
47.630359,
-122.138669
],
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
]
},
{
"type": "Point",
"coordinates": [
47.630563,
-122.1387383
],
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
],
"matchCodes": [
"Good"
]
}
]
}
],
"statusCode": 200,
"statusDescription": "OK",
"traceId": "e0a7cb31a835ffbcc7e2b8f6b1a0b4e0|MWH0032BE3|0.0.0.1|Ref A: 9BC4F0B708B04F2EA6D52CB3461458A6 Ref B: CO1EDGE1411 Ref C: 2024-04-23T23:44:47Z"
下列 JSON 範例顯示執行 Azure 地圖服務的取得地理編碼要求時，HTTP 回應的本文中傳回的內容：
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.138679,
47.630356
]
},
"bbox": [
-122.14632082377759,
47.62649328242932,
-122.1310371762224,
47.634218717570675
],
"properties": {
"type": "Address",
"confidence": "High",
"matchCodes": [
"Good"
],
"geocodePoints": [
{
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
],
"geometry": {
"type": "Point",
"coordinates": [
-122.138679,
47.630356
]
}
},
{
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
],
"geometry": {
"type": "Point",
"coordinates": [
-122.138685,
47.6305637
]
}
}
],
"address": {
"addressLine": "15127 NE 24th St",
"postalCode": "98052",
"locality": "Redmond",
"formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
"countryRegion": {
"name": "United States",
"ISO": "US"
},
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King County"
}
]
}
}
}
]
}
交易使用方式
如同 Bing 地圖服務的依地址尋找位置 API，Azure 地圖服務的取得地理編碼 API 會為每個要求記錄一筆可計費交易。 如需 Azure 地圖服務交易的詳細資訊，請參閱了解 Azure 地圖服務交易。
其他資訊
- 取得地理編碼批次：用來在單一同步要求中將查詢批次傳送至取得地理編碼 API。
支援