Search - Get Reverse Geocoding
使用 從經度和緯度座標取得街道位址和位置資訊。
Get Reverse Geocoding
API 是用來將座標轉譯 (範例的 HTTP GET
要求:37.786505、-122.3862) 為人類可理解的街道位址。 適用於追蹤您從裝置或資產接收 GPS 摘要的應用程式,並想要知道與座標相關聯的位址。 此端點會傳回指定座標的地址資訊。
GET https://atlas.microsoft.com/reverseGeocode?api-version=2023-06-01&coordinates={coordinates}
GET https://atlas.microsoft.com/reverseGeocode?api-version=2023-06-01&coordinates={coordinates}&resultTypes={resultTypes}&view={view}
URI 參數
名稱 | 位於 | 必要 | 類型 | Description |
---|---|---|---|---|
api-version
|
query | True |
string |
Azure 地圖服務 API 的版本號碼。 |
coordinates
|
query | True |
number[] |
您要反轉地理編碼之位置的座標。 範例:&座標=lon,lat |
result
|
query |
在回應中指定您想要的實體類型。 只會傳回您指定的類型。 如果點無法對應至您指定的實體類型,則回應中不會傳回任何位置資訊。 預設值為所有可能的實體。 從下列選項選取的實體類型逗號分隔清單。
這些實體類型會從最特定的實體排序到最不特定的實體。 找到多個實體類型的實體時,只會傳回最特定的實體。 例如,如果您將 Address 和 AdminDistrict1 指定為兩種類型的實體類型和實體,則回應中只會傳回 Address 實體資訊。 |
||
view
|
query |
string |
表示 ISO 3166-1 Alpha-2 區域/國家/地區代碼的字串。 這會改變地緣政治爭議框線和標籤,以符合指定的用戶區域。 根據預設,View 參數會設定為 「Auto」,即使您尚未在要求中定義此參數也一樣。 如需詳細資訊,請參閱 支援的檢視 ,並查看可用的檢視。 |
要求標頭
名稱 | 必要 | 類型 | Description |
---|---|---|---|
x-ms-client-id |
string |
指定哪一個帳戶是與 Azure AD 安全性模型搭配使用。 它代表 Azure 地圖服務帳戶的唯一標識碼,而且可以從 Azure 地圖服務管理平面帳戶 API 擷取。 若要在 Azure 地圖服務中使用 Azure AD 安全性,請參閱下列 文章 以取得指引。 |
|
Accept-Language |
string |
應該傳回搜尋結果的語言。 如需詳細資訊,請參閱 支援的語言 。 |
回應
名稱 | 類型 | Description |
---|---|---|
200 OK |
確定 Media Types: "application/geo+json" |
|
Other Status Codes |
發生意外錯誤。 Media Types: "application/geo+json" |
安全性
AADToken
這些是 entra OAuth 2.0 Flow Microsoft 。 與 Azure 角色型存 取控制配對時,可用來控制對 Azure 地圖服務 REST API 的存取。 Azure 角色型訪問控制可用來指定一或多個 Azure 地圖服務資源帳戶或子資源的存取權。 任何使用者、群組或服務主體都可以透過內建角色或由一或多個 Azure 地圖服務 REST API 許可權組成的自定義角色來授與存取權。
若要實作案例,建議您檢視 驗證概念。 總而言之,此安全性定義提供一個解決方案,可透過能夠針對特定 API 和範圍進行存取控制的物件,將應用程式模型化 () 。
注意
- 此安全性定義 需要使用
x-ms-client-id
標頭來指出應用程式要求存取權的 Azure 地圖服務資源。 這可以從 地圖服務管理 API 取得。 -
Authorization URL
專屬於 Azure 公用雲端實例。 主權雲端具有唯一的授權 URL,Microsoft Entra ID 設定。 - 透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API,從 Azure 管理平面 設定 Azure 角色型存取控制。
- Azure 地圖服務 Web SDK 的使用方式允許針對多個使用案例設定應用程式。
- 如需Microsoft身分識別平臺的詳細資訊,請參閱 Microsoft身分識別平臺概觀。
類型:
oauth2
Flow:
implicit
授權 URL:
https://login.microsoftonline.com/common/oauth2/authorize
範圍
名稱 | Description |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
這是透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API 透過 Azure 管理平面建立 Azure 地圖服務資源 時所佈建的共用密鑰。
使用此金鑰時,任何應用程式都會獲得存取所有 REST API 的授權。 換句話說,這些目前可視為發行帳戶的主要密鑰。
對於公開的應用程式,我們建議使用 Azure 地圖服務 REST API 的伺服器對伺服器存取,以便安全地儲存此密鑰。
類型:
apiKey
位於:
header
SAS Token
這是透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API,從 Azure 地圖服務資源 上的清單 SAS 作業建立共用存取簽章令牌。
使用此令牌時,任何應用程式都有權使用 Azure 角色型訪問控制進行存取,並精細控制到期、速率和區域 (特定令牌的使用) 。 換句話說,SAS 令牌可用來允許應用程式以比共用密鑰更安全的方式控制存取。
對於公開的應用程式,我們建議在 地圖帳戶資源 上設定允許的來源特定清單,以限制轉譯濫用,並定期更新 SAS 令牌。
類型:
apiKey
位於:
header
範例
Search point -122.138681, 47.630358
範例要求
GET https://atlas.microsoft.com/reverseGeocode?api-version=2023-06-01&coordinates=-122.138681,47.630358
範例回覆
Content-Type: application/geo+json
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"address": {
"countryRegion": {
"name": "United States"
},
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King County"
}
],
"formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
"locality": "Redmond",
"postalCode": "98052",
"addressLine": "15127 NE 24th St"
},
"type": "Address",
"confidence": "Medium",
"matchCodes": [
"Good"
],
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.138681,
47.630358
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
]
},
{
"geometry": {
"type": "Point",
"coordinates": [
-122.1386787,
47.6302179
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-122.138681,
47.630358
]
},
"bbox": [
-122.14632282407,
47.626495282429325,
-122.13103917593001,
47.63422071757068
]
}
]
}
定義
名稱 | Description |
---|---|
Address |
結果的位址 |
Admin |
位址之國家或地區的細分名稱。 此元素通常被視為第一個訂單系統管理細分,但在某些情況下,它也會包含國家/地區、相依性或區域中的第二個、第三個或第四個順序細分。 |
Calculation |
用來計算地理編碼點的方法。 |
Confidence |
地理編碼位置結果為相符的信賴等級。 將此值與比對程式代碼搭配使用,以判斷比對的更完整資訊。 地理編碼位置的信賴度是以許多因素為基礎,包括地理編碼位置的相對重要性和使用者的位置。如果指定的話。 |
Country |
|
Error |
資源管理錯誤其他資訊。 |
Error |
錯誤詳細數據。 |
Error |
錯誤回應 |
Feature |
FeatureCollection 對象的類型必須是FeatureCollection。 |
Features |
|
Feature |
功能的類型必須是Feature。 |
Geocode |
地理編碼點的集合,其計算方式和建議的使用方式不同。 |
Geocoding |
此物件是從成功的地理編碼呼叫傳回 |
Geo |
有效的 |
Intersection |
結果的位址。 |
Match |
一或多個比對程式代碼值,代表回應中每個位置的地理編碼層級。 例如,具有相符代碼的 同樣地,具有相符碼的 可能的值包括:
|
Properties | |
Reverse |
在回應中指定您想要的實體類型。 只會傳回您指定的類型。 如果點無法對應至您指定的實體類型,回應中不會傳回任何位置資訊。 預設值是所有可能的實體。 從下列選項選取的實體類型逗號分隔清單。
這些實體類型會從最特定的實體排序到最不特定的實體。 找到多個實體類型的實體時,只會傳回最特定的實體。 例如,如果您將 Address 和 AdminDistrict1 指定為這兩種類型的實體類型和實體,則回應中只會傳回 Address 實體資訊。 |
Usage |
最適合用於地理編碼點。
每個地理編碼點都會定義為 |
Address
結果的位址
名稱 | 類型 | Description |
---|---|---|
addressLine |
string |
包含街地名和號碼的 AddressLine |
adminDistricts |
位址之國家或地區的細分名稱。 此元素通常被視為第一個訂單系統管理細分,但在某些情況下,它也會包含國家/地區、相依性或區域中的第二個、第三個或第四個順序細分。 |
|
countryRegion | ||
formattedAddress |
string |
格式化的 Address 屬性 |
intersection |
結果的位址。 |
|
locality |
string |
locality 屬性 |
neighborhood |
string |
芳鄰屬性 |
postalCode |
string |
郵遞區號屬性 |
AdminDistricts
位址之國家或地區的細分名稱。 此元素通常被視為第一個訂單系統管理細分,但在某些情況下,它也會包含國家/地區、相依性或區域中的第二個、第三個或第四個順序細分。
名稱 | 類型 | Description |
---|---|---|
name |
string |
對應 adminDistrict 字段的名稱,針對 adminDistrict[0],這可能是州的完整名稱,例如 Washington、For adminDistrict[1],這可能是縣/市的完整名稱 |
shortName |
string |
對應 adminDistrict 字段的簡短名稱 For adminDistrict[0],這可能是 WA、針對 adminDistrict[1] 等狀態的簡短名稱,這可能是縣/市的簡短名稱 |
CalculationMethodEnum
用來計算地理編碼點的方法。
名稱 | 類型 | Description |
---|---|---|
Interpolation |
string |
地理編碼點已使用插補來比對道路上的點。 |
InterpolationOffset |
string |
地理編碼點與道路上的點相符,使用插補與額外的位移,將點移到街道的側邊。 |
Parcel |
string |
地理編碼點與包裹中心相符。 |
Rooftop |
string |
地理編碼點已與建築物的頂點相符。 |
ConfidenceEnum
地理編碼位置結果為相符的信賴等級。 將此值與比對程式代碼搭配使用,以判斷比對的更完整資訊。
地理編碼位置的信賴度是以許多因素為基礎,包括地理編碼位置的相對重要性和使用者的位置。如果指定的話。
名稱 | 類型 | Description |
---|---|---|
High |
string |
如果信賴度設定為 如果要求包含位置或檢視,則排名可能會適當地變更。 例如,“Paris” 的位置查詢會傳回 “Paris, France” 和 “Paris, TX” 兩者皆具有 |
Low |
string |
|
Medium |
string |
在某些情況下,傳回的相符專案可能與要求中提供的資訊層級不同。 例如,要求可以指定地址資訊,而地理編碼服務可能只能比對郵遞區編碼。 在此情況下,如果地理編碼服務確信郵遞區編碼符合數據,則會將信賴度設定為 如果查詢中的位置資訊模棱兩可,而且沒有其他資訊可排名位置 (例如使用者位置或位置) 的相對重要性,則信賴度會設定為 如果查詢中的位置資訊未提供足夠的資訊來地理編碼特定位置,可能會傳回較不精確的位置值,並將信賴度設定為 |
CountryRegion
名稱 | 類型 | Description |
---|---|---|
ISO |
string |
國家/地區的 ISO |
name |
string |
國家/地區的名稱 |
ErrorAdditionalInfo
資源管理錯誤其他資訊。
名稱 | 類型 | Description |
---|---|---|
info |
object |
其他資訊。 |
type |
string |
其他信息類型。 |
ErrorDetail
錯誤詳細數據。
名稱 | 類型 | Description |
---|---|---|
additionalInfo |
錯誤其他資訊。 |
|
code |
string |
錯誤碼。 |
details |
錯誤詳細資料。 |
|
message |
string |
錯誤訊息。 |
target |
string |
錯誤目標。 |
ErrorResponse
錯誤回應
名稱 | 類型 | Description |
---|---|---|
error |
錯誤物件。 |
FeatureCollectionEnum
FeatureCollection 對象的類型必須是FeatureCollection。
名稱 | 類型 | Description |
---|---|---|
FeatureCollection |
string |
FeaturesItem
名稱 | 類型 | Description |
---|---|---|
bbox |
number[] |
周框方塊。 使用的投影 - EPSG:3857。 如需詳細資訊,請參閱 RFC 7946 。 |
geometry |
有效的 |
|
id |
string |
傳回之功能的標識碼 |
properties | ||
type |
功能的類型必須是Feature。 |
FeatureTypeEnum
功能的類型必須是Feature。
名稱 | 類型 | Description |
---|---|---|
Feature |
string |
GeocodePoints
地理編碼點的集合,其計算方式和建議的使用方式不同。
名稱 | 類型 | Description |
---|---|---|
calculationMethod |
用來計算地理編碼點的方法。 |
|
geometry |
有效的 |
|
usageTypes |
最適合用於地理編碼點。
每個地理編碼點都會定義為 |
GeocodingResponse
此物件是從成功的地理編碼呼叫傳回
名稱 | 類型 | Description |
---|---|---|
features | ||
nextLink |
string |
是傳回之功能下一頁的連結。 如果是最後一頁,則不會有此欄位。 |
type |
FeatureCollection 對象的類型必須是FeatureCollection。 |
GeoJsonPoint
有效的 GeoJSON Point
幾何類型。 如需詳細資訊,請參閱 RFC 7946 。
名稱 | 類型 | Description |
---|---|---|
bbox |
number[] |
周框方塊。 使用的投影 - EPSG:3857。 如需詳細資訊,請參閱 RFC 7946 。 |
coordinates |
number[] |
|
type |
string:
Point |
指定 |
Intersection
結果的位址。
名稱 | 類型 | Description |
---|---|---|
baseStreet |
string |
位置的主要街道。 |
displayName |
string |
交集的完整名稱。 |
intersectionType |
string |
交集的類型。 |
secondaryStreet1 |
string |
第一個交集街道。 |
secondaryStreet2 |
string |
如果有的話,第二個交集街道。 |
MatchCodesEnum
一或多個比對程式代碼值,代表回應中每個位置的地理編碼層級。
例如,具有相符代碼的 Good
地理編碼位置,表示 Ambiguous
找到多個地理位置資訊,而且地理編碼服務沒有搜尋上層來尋找相符專案。
同樣地,具有相符碼的 Ambiguous
地理編碼位置,表示 UpHierarchy
找不到符合所有提供的位置資訊,因此地理編碼服務必須搜尋上階層,並在該層級找到多個相符專案。 和 UpHierarchy
結果的Ambiguous
範例是當您提供完整的地址資訊,但地理編碼服務找不到街地道址的相符專案,而是傳回多個 RoadBlock 值的資訊。
可能的值包括:
Good
:位置只有一個相符專案,或所有傳回的相符專案都視為強式相符專案。 例如,紐約的查詢會傳回數個 Good 相符專案。
Ambiguous
:位置是一組可能的相符專案之一。 例如,當您查詢街道位址 128 主要 St.時,回應可能會傳回 128 北主要 St 和 128 南主要 St 的兩個位置,因為沒有足夠的資訊可判斷要選擇的選項。
UpHierarchy
:位置代表向上移動地理階層。 當找不到位置要求的相符專案時,就會發生這種情況,因此會傳回較不精確的結果。 例如,如果找不到所要求位址的相符專案,則可能會傳回與 RoadBlock 實體類型的 相符代碼 UpHierarchy
。
名稱 | 類型 | Description |
---|---|---|
Ambiguous |
string |
|
Good |
string |
|
UpHierarchy |
string |
Properties
名稱 | 類型 | Description |
---|---|---|
address |
結果的位址 |
|
confidence |
地理編碼位置結果為相符的信賴等級。 將此值與比對程式代碼搭配使用,以判斷比對的更完整資訊。 地理編碼位置的信賴度是以許多因素為基礎,包括地理編碼位置的相對重要性和使用者的位置。如果指定的話。 |
|
geocodePoints |
地理編碼點的集合,其計算方式與建議的使用方式不同。 |
|
matchCodes |
一或多個比對程式代碼值,代表回應中每個位置的地理編碼層級。 例如,具有相符代碼的 同樣地,具有相符碼的 可能的值包括:
|
|
type |
string |
值為下列其中之一:
|
ReverseGeocodingResultTypeEnum
在回應中指定您想要的實體類型。 只會傳回您指定的類型。 如果點無法對應至您指定的實體類型,回應中不會傳回任何位置資訊。 預設值是所有可能的實體。 從下列選項選取的實體類型逗號分隔清單。
- 位址
- 「鄰近地區」
- PopulatedPlace
- Postcode1
- AdminDivision1
- AdminDivision2
- CountryRegion
這些實體類型會從最特定的實體排序到最不特定的實體。 找到多個實體類型的實體時,只會傳回最特定的實體。 例如,如果您將 Address 和 AdminDistrict1 指定為這兩種類型的實體類型和實體,則回應中只會傳回 Address 實體資訊。
名稱 | 類型 | Description |
---|---|---|
Address |
string |
|
AdminDivision1 |
string |
|
AdminDivision2 |
string |
|
CountryRegion |
string |
|
Neighborhood |
string |
|
PopulatedPlace |
string |
|
Postcode1 |
string |
UsageTypeEnum
最適合用於地理編碼點。
每個地理編碼點都會定義為 Route
點、 Display
點或兩者。
如果您要建立位置的路線,請使用 Route
點。 如果您要在地圖上顯示位置,請使用 Display
點。 例如,如果位置是一個駐留, Route
點可能會指定您可以用汽車進入的駐留,而 Display
某個點可能是指定駐留中心的點。
名稱 | 類型 | Description |
---|---|---|
Display |
string |
|
Route |
string |