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	指定在地理位置上執行的篩選層級。縮小指定地理實體類型的搜尋範圍，例如只傳回城市。產生的回應將包含地理位置標識符，以及相符的實體類型。如果您提供多個實體做為逗號分隔清單，端點會傳回「可用的最小實體」。傳回的 Geometry 識別碼可用來透過取得搜尋多邊形 API 來取得該地理位置的幾何。設定 entityType 時，會忽略下列參數：標題數字 returnRoad使用 returnSpeedLimit 道路使用返回匹配類型
heading	query		integer minimum: -360 maximum: 360	以度為單位的車輛方向行駛，用於沿著路段行駛。 0 為 North、90 為 East 等等，值範圍從 -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 參數，仍會設定為 “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

這些是 Entra OAuth 2.0 流程 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 角色型訪問控制是從 azure 管理平面設定，透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API。
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 入口網站、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 參數，仍會設定為 “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

Object

結果的位址

名稱	類型	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 蘇格蘭和 ON for On for On。
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	Sub / Super City
neighbourhood	string	鄰里是城市或城鎮內一個地理上本地化的區域，具有鮮明的特點和居民之間的社會互動。
postalCode	string	郵遞區編碼 /郵遞區號
routeNumbers	string[]	用來明確識別街道的代碼
street	string	街道名稱。已被取代，請改用 streetName。
streetName	string	街道名稱。
streetNameAndNumber	string	街道名稱和號碼。
streetNumber	string	街上的建築編號。

BoundingBoxCompassNotation

Object

位置的周框方塊。

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

Entity

列舉型別

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

值	Description
position	位置實體

ErrorAdditionalInfo

Object

資源管理錯誤其他資訊。

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

ErrorDetail

Object

錯誤詳細數據。

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

ErrorResponse

Object

錯誤回應

名稱	類型	Description
error	ErrorDetail	error 物件。

GeographicEntityType

列舉型別

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

值	Description
Country	國家/地區名稱
CountrySecondarySubdivision	縣
CountrySubdivision	州或省
CountryTertiarySubdivision	具名區域
Municipality	城市/城鎮
MunicipalitySubdivision	Sub / Super City
Neighbourhood	附近
PostalCodeArea	郵遞區編碼 /郵遞區號

LatLongPairAbbreviated

Object

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

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

LocalizedMapView

列舉型別

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

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

值	Description
AE	阿拉伯聯合大國（阿拉伯視圖）
AR	阿根廷（阿根廷觀點）
Auto	根據要求的IP位址傳回地圖數據。
BH	巴林（阿拉伯檢視）
IN	印度（印度觀點）
IQ	伊拉克（阿拉伯文檢視）
JO	約旦（阿拉伯文檢視）
KW	科威特（阿拉伯文視圖）
LB	黎巴嫩（阿拉伯文檢視）
MA	摩洛哥（摩洛哥檢視）
OM	阿曼（阿拉伯文視圖）
PK	巴基斯坦（巴基斯坦觀點）
PS	巴勒斯坦權力機構（阿拉伯文視圖）
QA	卡達（阿拉伯文檢視）
SA	沙烏地阿拉伯（阿拉伯文視圖）
SY	敘利亞（阿拉伯文檢視）
Unified	統一檢視（其他）
YE	葉門（阿拉伯文檢視）

MatchType

列舉型別

反向位址搜尋作業的比對類型。

值	Description
AddressPoint
HouseNumberRange
Street

QueryType

列舉型別

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

值	Description
NEARBY	搜尋是在具有定義半徑的特定緯度和經度周圍執行
NON_NEAR	搜尋是在全域執行，而不會偏向特定緯度和經度，也沒有定義的半徑

ResponseFormat

列舉型別

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

值	Description
json	JavaScript 物件表示法數據交換格式
xml	可延伸標記語言

ReverseSearchAddressResult

Object

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

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

ReverseSearchAddressResultItem

Object

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

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

RoadUseType

列舉型別

描述道路的可能用法。

值	Description
Arterial
LimitedAccess
LocalStreet
Ramp
Rotary
Terminal

SearchSummary

Object

搜尋 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	找到的結果總數。

共用方式為

Search - Get Search Address Reverse

URI 參數

要求標頭

回應

安全性

AADToken

範圍

subscription-key

SAS Token

範例

Searches addresses for coordinates 37.337,-121.89

範例要求

範例回覆

定義

Address

BoundingBoxCompassNotation

Entity

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

GeographicEntityType

LatLongPairAbbreviated

LocalizedMapView

MatchType

QueryType

ResponseFormat

ReverseSearchAddressResult

ReverseSearchAddressResultItem

RoadUseType

SearchSummary