Search - Get Search Address Reverse

服務:

Maps

API 版本:

1.0

用來從緯度和經度座標取得街地道址和位置資訊。
Get Search Address Reverse當指定緯度和經度座標時，API 是 和 HTTP GET 要求，會傳回街地道址或位置。

有時候您可能需要將座標轉譯為 (範例：37.786505、-122.3862) 成人類可理解的街地道址。 在追蹤您從裝置或資產接收 GPS 摘要的應用程式時，最常需要這項功能，並想要知道座標所在的位址。 此端點會傳回指定座標的地址資訊。

GET https://atlas.microsoft.com/search/address/reverse/{format}?api-version=1.0&query={query}

含選擇性參數:

GET https://atlas.microsoft.com/search/address/reverse/{format}?api-version=1.0&query={query}&language={language}&returnSpeedLimit={returnSpeedLimit}&heading={heading}&radius={radius}&number={number}&returnRoadUse={returnRoadUse}&roadUse={roadUse}&allowFreeformNewline={allowFreeformNewline}&returnMatchType={returnMatchType}&entityType={entityType}&view={view}

URI 參數

名稱	位於	必要	類型	Description
format	path	True	ResponseFormat	所需的回應格式。 值可以是 json 或 xml。
api-version	query	True	string	Azure 地圖服務 API 的版本號碼。
query	query	True	number[]	指定為逗號分隔字串的適用查詢，後面接著經度，例如 “47.641268，-122.125679”。
allowFreeformNewline	query		boolean	格式化位址中的換行符格式。 如果為 true，則位址將包含換行符。 如果為 false，換行符將會轉換成逗號。
entityType	query		GeographicEntityType	指定在地理位置上執行的篩選層級。 縮小指定地理實體類型的搜尋範圍，例如只傳回一些資源。 產生的回應會包含地理標識符，以及相符的實體類型。 如果您以逗號分隔清單的形式提供多個實體，端點將會傳回「可用的最小實體」。 傳回的幾何標識碼可用來透過 Get 搜尋 Polygon API 取得該地理位置的幾何。 設定 entityType 時，會忽略下列參數： 標題 number returnRoadUse returnSpeedLimit roadUse returnMatchType
heading	query		integer	車輛的方向標題，用於沿著道路的一段行進。 0 是北，90 是東部等等，值範圍從 -360 到 360。 有效位數最多可以包含一個小數字數
language	query		string	應該傳回搜尋結果的語言。 應該是其中一個支援的 IETF 語言標記，不區分大小寫。 當特定欄位無法使用指定語言的數據時，會使用預設語言。 如需詳細資訊，請參閱 支援的語言 。
number	query		string	街地道號做為字串。 如果數位連同要求一起傳送，回應可能包含街道的側邊 (左/右) ，以及該數位的位移位置
radius	query		integer	以公尺為單位的半徑，讓結果受限於定義的區域
returnMatchType	query		boolean	包含回應中達成之地理編碼器相符專案類型的資訊。
returnRoadUse	query		boolean	布林值。 若要在街地道層級啟用反向地理編碼的道路使用數位傳回
returnSpeedLimit	query		boolean	布林值。 啟用已張貼速度限制的傳回
roadUse	query		RoadUseType[]	將反向地理編碼限制為特定類型的道路使用。 反向地理編碼的道路使用數位可以是一或多個 LimitedAccess、一般、終端機、坡形、旋轉、LocalStreet
view	query		LocalizedMapView	View 參數 (也稱為「用戶區域」參數) 可讓您針對特定國家/地區顯示地緣政治爭議區域的正確地圖。 不同的國家/地區具有這類區域的不同檢視，而 View 參數可讓應用程式符合應用程式將提供服務的國家/地區所需的檢視。 根據預設，即使您尚未在要求中定義 View 參數，View 參數也會設定為 “Unified”。 您必須負責判斷使用者的位置，然後正確設定該位置的 View 參數。 或者，您可以選擇設定 'View=Auto'，這會根據要求的IP位址傳回地圖數據。 Azure 地圖服務 中的 View 參數必須符合適用的法律，包括對應、地圖、影像和其他數據，以及您有權透過 Azure 地圖服務 存取的第三方內容。 範例：view=IN。 如需詳細資訊，請參閱 支援的檢視 ，並查看可用的檢視。

要求標頭

名稱	必要	類型	Description
x-ms-client-id		string	指定哪個帳戶與 Microsoft Entra ID 安全性模型搭配使用。 它代表 Azure 地圖服務 帳戶的唯一標識符，而且可以從 Azure 地圖服務 管理平面帳戶 API 擷取。 若要在 Azure 地圖服務 中使用 Microsoft Entra ID 安全性，請參閱下列文章以取得指引。

回應

名稱	類型	Description
200 OK	ReverseSearchAddressResult	確定
Other Status Codes	ErrorResponse	發生意外錯誤。

安全性

AADToken

這些是 Microsoft Entra OAuth 2.0 流程。 與 Azure 角色型存取控制配對時，可用來控制對 #D6AD8453552CC4921864057313B6D84B4 REST API 的存取。 Azure 角色型訪問控制可用來指定一或多個 Azure 地圖服務 資源帳戶或子資源的存取權。 任何使用者、群組或服務主體都可以透過內建角色或由一或多個許可權組成的自定義角色來授與存取權，以 Azure 地圖服務 REST API。

若要實作案例，建議您檢視 驗證概念。 總而言之，此安全性定義會透過能夠針對特定 API 和範圍進行訪問控制的物件，提供將應用程式模型化 () 的解決方案。

注意

• 此安全性定義需要使用x-ms-client-id 標頭來指出應用程式要求存取權 Azure 地圖服務 資源。 這可以從 地圖管理 API 取得。
• Authorization URL專屬於 Azure 公用雲端實例。 主權雲端具有唯一的授權 URL 和 Microsoft Entra ID 設定。
• Azure 角色型訪問控制是透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API 從 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 地圖服務 帳戶時所佈建的共用密鑰。

使用此金鑰，任何應用程式都可以存取所有 REST API。 換句話說，此金鑰可作為發行所在帳戶中的主要金鑰。

對於公開的應用程式，我們建議使用機密用戶端應用程式方法來存取 Azure 地圖服務 REST API，以便安全地儲存您的密鑰。

類型: apiKey
位於: query

SAS Token

這是透過 azure 管理平面透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API，從 Azure 地圖服務 資源上的列出 SAS 作業建立的共用存取簽章令牌。

使用此令牌時，任何應用程式都有權使用 Azure 角色型訪問控制進行存取，並更精細地控制到期、速率和區域 (特定令牌的使用) 。 換句話說，SAS 令牌可用來允許應用程式以比共用密鑰更安全的方式來控制存取。

對於公開的應用程式，我們建議在 地圖帳戶資源 上設定允許的來源特定清單，以限制轉譯濫用，並定期更新 SAS 令牌。

類型: apiKey
位於: header

範例

Searches addresses for coordinates 37.337,-121.89

範例要求

HTTP

GET https://atlas.microsoft.com/search/address/reverse/json?api-version=1.0&query=37.337,-121.89

範例回覆

狀態碼:

200

{
  "summary": {
    "queryTime": 5,
    "numResults": 1
  },
  "addresses": [
    {
      "address": {
        "streetNumber": "31",
        "routeNumbers": [],
        "streetName": "N 2nd St",
        "streetNameAndNumber": "31 N 2nd St",
        "countryCode": "US",
        "countrySubdivisionCode": "CA",
        "countrySubdivisionName": "California",
        "municipality": "San Jose",
        "postalCode": "95113",
        "country": "United States of America",
        "countryCodeISO3": "USA",
        "freeformAddress": "31 N 2nd St, San Jose CA 95113",
        "extendedPostalCode": "951131217"
      },
      "position": "37.337090,-121.889820"
    }
  ]
}

定義

名稱	Description
Address	結果的位址
BoundingBoxCompassNotation	位置的周框方塊。
Entity	周框方塊的實體類型來源。 針對反向地理編碼，這一律等於位置。
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細數據。
ErrorResponse	錯誤回應
GeographicEntityType	Geography 實體類型。 只有在要求 entityType 且可供使用時才存在。
LatLongPairAbbreviated	以緯度和經度表示的位置，使用簡短名稱 『lat』 & 『lon』。
LocalizedMapView	View 參數 (也稱為「用戶區域」參數) 可讓您針對特定國家/地區顯示地緣政治爭議區域的正確地圖。 不同的國家/地區具有這類區域的不同檢視，而 View 參數可讓應用程式符合應用程式將提供服務的國家/地區所需的檢視。 根據預設，即使您尚未在要求中定義 View 參數，View 參數也會設定為 “Unified”。 您必須負責判斷使用者的位置，然後正確設定該位置的 View 參數。 或者，您可以選擇設定 'View=Auto'，這會根據要求的IP位址傳回地圖數據。 Azure 地圖服務 中的 View 參數必須符合適用的法律，包括地圖、影像和其他數據，以及您授權透過 Azure 地圖服務 存取的第三方內容的國家/地區對應相關參數。 範例：view=IN。 如需詳細資訊，請參閱 支援的檢視 ，並查看可用的檢視。
MatchType	反向位址搜尋作業的相符類型。
QueryType	要傳回的查詢類型：NEARBY 或 NON_NEAR。
ResponseFormat	所需的回應格式。 值可以是 json 或 xml。
ReverseSearchAddressResult	此物件會從成功的位址反向呼叫傳回 搜尋
ReverseSearchAddressResultItem	搜尋 位址反向回應的結果物件
RoadUseType	描述道路的可能用法。
SearchSummary	搜尋 API 回應的 Summary 物件。

Address

結果的位址

名稱	類型	Description
boundingBox	BoundingBoxCompassNotation	位置的周框方塊。
buildingNumber	string	街上的建築物編號。 已淘汰，請改用 streetNumber。
country	string	國家/地區名稱
countryCode	string	國家/地區 (注意：這是兩個字母的代碼，而不是國家/地區名稱。)
countryCodeISO3	string	ISO Alpha-3 國家/地區代碼
countrySecondarySubdivision	string	郡/縣
countrySubdivision	string	省/市
countrySubdivisionCode	string	countrySubdivisionCode 前面加上 countryCode ( countryCode-countrySubdivisionCode ) ，而連字元會形成 ISO 3166-2 程序代碼。 範例：TX for Texas、SCT for Texas 和 ON for On for Ontario。
countrySubdivisionName	string	國家/地區系統管理階層的第一層完整名稱。 只有在 countrySubdivision 以縮寫形式呈現時，才會顯示此字段。 僅支援美國、加拿大和英國。
countryTertiarySubdivision	string	具名區域
crossStreet	string	要交叉的街道名稱。
extendedPostalCode	string	延伸郵遞區編碼 (可用性取決於區域) 。
freeformAddress	string	根據結果的國家/地區/地區格式規則格式化的位址行，或在國家/地區的情況下，其完整國家/地區名稱。
localName	string	位址元件，代表將多個可尋址物件分組以進行尋址用途的地理區域或位置名稱，而不做為管理單位。 此欄位是用來建置 freeformAddress 屬性。 localName 代表郵遞。 視位置而定， localName 是城市或鎮的已知名稱。 對於城市或城市常用的名稱，請使用 localName ，而不是 municipality。
municipality	string	城市/城市/鎮 注意： municipality 代表居民。 視位置而定， municipality 值可能與城市或鎮的常見已知名稱不同。 對於城市或城市常用的名稱，建議 localName 使用值，而不是 municipality 值。
municipalitySubdivision	string	子/超級城市
neighbourhood	string	一個街道是城市或城市內的地理當地語系化區域，具有獨特特性，以及各地方之間的社交互動。
postalCode	string	郵遞區區編碼/郵遞區號
routeNumbers	string[]	用來明確識別街道的代碼
street	string	街地名。 已淘汰，請改用 streetName。
streetName	string	街地名。
streetNameAndNumber	string	街地名和數位。
streetNumber	string	街上的建築物編號。

BoundingBoxCompassNotation

位置的周框方塊。

名稱	類型	Description
entity	Entity	周框方塊的實體類型來源。 針對反向地理編碼，這一律等於位置。
northEast	string	以逗號分隔浮點數作為周框方塊的北東部緯度、經度座標
southWest	string	周框方塊的南西部緯度、經度座標，以逗號分隔的浮點數

Entity

周框方塊的實體類型來源。 針對反向地理編碼，這一律等於位置。

名稱	類型	Description
position	string	位置實體

ErrorAdditionalInfo

資源管理錯誤其他資訊。

名稱	類型	Description
info	object	其他資訊。
type	string	其他信息類型。

ErrorDetail

錯誤詳細數據。

名稱	類型	Description
additionalInfo	ErrorAdditionalInfo[]	錯誤其他資訊。
code	string	錯誤碼。
details	ErrorDetail[]	錯誤詳細資料。
message	string	錯誤訊息。
target	string	錯誤目標。

ErrorResponse

錯誤回應

名稱	類型	Description
error	ErrorDetail	錯誤物件。

GeographicEntityType

Geography 實體類型。 只有在要求 entityType 且可供使用時才存在。

名稱	類型	Description
Country	string	國家/地區名稱
CountrySecondarySubdivision	string	郡/縣
CountrySubdivision	string	省/市
CountryTertiarySubdivision	string	具名區域
Municipality	string	城市/城市/鎮
MunicipalitySubdivision	string	子/超級城市
Neighbourhood	string	附近
PostalCodeArea	string	郵遞區區編碼/郵遞區號

LatLongPairAbbreviated

以緯度和經度表示的位置，使用簡短名稱 『lat』 & 『lon』。

名稱	類型	Description
lat	number	Latitude 屬性
lon	number	經度屬性

LocalizedMapView

View 參數 (也稱為「用戶區域」參數) 可讓您針對特定國家/地區顯示地緣政治爭議區域的正確地圖。 不同的國家/地區具有這類區域的不同檢視，而 View 參數可讓應用程式符合應用程式將提供服務的國家/地區所需的檢視。 根據預設，即使您尚未在要求中定義 View 參數，View 參數也會設定為 “Unified”。 您必須負責判斷使用者的位置，然後正確設定該位置的 View 參數。 或者，您可以選擇設定 'View=Auto'，這會根據要求的IP位址傳回地圖數據。 Azure 地圖服務 中的 View 參數必須符合適用的法律，包括地圖、影像和其他數據，以及您授權透過 Azure 地圖服務 存取的第三方內容的國家/地區對應相關參數。 範例：view=IN。

如需詳細資訊，請參閱 支援的檢視 ，並查看可用的檢視。

名稱	類型	Description
AE	string	阿拉伯聯合大公國 (阿拉伯文檢視)
AR	string	阿根廷 (阿根廷文檢視)
Auto	string	根據要求的 IP 位址傳回地圖資料。
BH	string	巴林 (阿拉伯文檢視)
IN	string	印度 (印度文檢視)
IQ	string	伊拉克 (阿拉伯文檢視)
JO	string	約旦 (阿拉伯文檢視)
KW	string	科威特 (阿拉伯文檢視)
LB	string	黎巴嫩 (阿拉伯文檢視)
MA	string	摩洛哥 (摩洛哥文檢視)
OM	string	阿曼 (阿拉伯文檢視)
PK	string	巴基斯坦 (巴基斯坦文檢視)
PS	string	巴勒斯坦民族權力機構 (阿拉伯文檢視)
QA	string	卡達 (阿拉伯文檢視)
SA	string	沙烏地阿拉伯 (阿拉伯文檢視)
SY	string	敘利亞 (阿拉伯文檢視)
Unified	string	整合檢視 (其他)
YE	string	葉門 (阿拉伯文檢視)

MatchType

反向位址搜尋作業的相符類型。

名稱	類型	Description
AddressPoint	string
HouseNumberRange	string
Street	string

QueryType

要傳回的查詢類型：NEARBY 或 NON_NEAR。

名稱	類型	Description
NEARBY	string	搜尋 是在具有定義半徑的特定緯度和經度周圍執行
NON_NEAR	string	搜尋 是在全域執行，而不會偏差為特定緯度和經度，且未定義半徑

ResponseFormat

所需的回應格式。 值可以是 json 或 xml。

名稱	類型	Description
json	string	JavaScript 物件表示法數據交換格式
xml	string	可延伸標記語言

ReverseSearchAddressResult

此物件會從成功的位址反向呼叫傳回 搜尋

名稱	類型	Description
addresses	ReverseSearchAddressResultItem[]	地址陣列
summary	SearchSummary	搜尋 位址反向回應的 Summary 物件

ReverseSearchAddressResultItem

搜尋 位址反向回應的結果物件

名稱	類型	Description
address	Address	結果的位址
matchType	MatchType	相符類型的相關信息。 值為下列其中之一： AddressPoint HouseNumberRange 街道
position	string	位置屬性的格式為 “{latitude}，{longitude}”
roadUse	RoadUseType[]	描述道路的可能用法。

RoadUseType

描述道路的可能用法。

名稱	類型	Description
Arterial	string
LimitedAccess	string
LocalStreet	string
Ramp	string
Rotary	string
Terminal	string

SearchSummary

搜尋 API 回應的 Summary 物件。

名稱	類型	Description
fuzzyLevel	integer	提供結果所需的最大模糊層級。
geoBias	LatLongPairAbbreviated	指出內部搜尋引擎何時套用地理空間偏差來改善結果的排名。 在某些方法中，設定可用的 lat 和 lon 參數可能會受到影響。 在其他情況下，它只是內部。
limit	integer	將傳回的回應數目上限
numResults	integer	回應中的結果數目。
offset	integer	完整結果集中傳回結果的起始位移。
query	string	用來產生這些搜尋結果的查詢參數。
queryTime	integer	解析查詢所花費的時間，以毫秒為單位。
queryType	QueryType	要傳回的查詢類型：NEARBY 或 NON_NEAR。
totalResults	integer	找到的結果總數。