共用方式為


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

resultTypes
query

ReverseGeocodingResultTypeEnum[]

在回應中指定您想要的實體類型。 只會傳回您指定的類型。 如果點無法對應至您指定的實體類型,則回應中不會傳回任何位置資訊。 預設值為所有可能的實體。 從下列選項選取的實體類型逗號分隔清單。

  • 位址
  • 「鄰近地區」
  • PopulatedPlace
  • Postcode1
  • AdminDivision1
  • AdminDivision2
  • CountryRegion

這些實體類型會從最特定的實體排序到最不特定的實體。 找到多個實體類型的實體時,只會傳回最特定的實體。 例如,如果您將 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

GeocodingResponse

確定

Media Types: "application/geo+json"

Other Status Codes

ErrorResponse

發生意外錯誤。

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

結果的位址

AdminDistricts

位址之國家或地區的細分名稱。 此元素通常被視為第一個訂單系統管理細分,但在某些情況下,它也會包含國家/地區、相依性或區域中的第二個、第三個或第四個順序細分。

CalculationMethodEnum

用來計算地理編碼點的方法。

ConfidenceEnum

地理編碼位置結果為相符的信賴等級。 將此值與比對程式代碼搭配使用,以判斷比對的更完整資訊。

地理編碼位置的信賴度是以許多因素為基礎,包括地理編碼位置的相對重要性和使用者的位置。如果指定的話。

CountryRegion
ErrorAdditionalInfo

資源管理錯誤其他資訊。

ErrorDetail

錯誤詳細數據。

ErrorResponse

錯誤回應

FeatureCollectionEnum

FeatureCollection 對象的類型必須是FeatureCollection。

FeaturesItem
FeatureTypeEnum

功能的類型必須是Feature。

GeocodePoints

地理編碼點的集合,其計算方式和建議的使用方式不同。

GeocodingResponse

此物件是從成功的地理編碼呼叫傳回

GeoJsonPoint

有效的 GeoJSON Point 幾何類型。 如需詳細資訊,請參閱 RFC 7946

Intersection

結果的位址。

MatchCodesEnum

一或多個比對程式代碼值,代表回應中每個位置的地理編碼層級。

例如,具有相符代碼的 Good 地理編碼位置,表示 Ambiguous 找到多個地理位置資訊,而且地理編碼服務沒有搜尋上層來尋找相符專案。

同樣地,具有相符碼的 Ambiguous 地理編碼位置,表示 UpHierarchy 找不到符合所有提供的位置資訊,因此地理編碼服務必須搜尋上階層,並在該層級找到多個相符專案。 和 UpHierarchy 結果的Ambiguous範例是當您提供完整的地址資訊,但地理編碼服務找不到街地道址的相符專案,而是傳回多個 RoadBlock 值的資訊。

可能的值包括:

Good:位置只有一個相符專案,或所有傳回的相符專案都視為強式相符專案。 例如,紐約的查詢會傳回數個 Good 相符專案。

Ambiguous:位置是一組可能的相符專案之一。 例如,當您查詢街道位址 128 主要 St.時,回應可能會傳回 128 北主要 St 和 128 南主要 St 的兩個位置,因為沒有足夠的資訊可判斷要選擇的選項。

UpHierarchy:位置代表向上移動地理階層。 當找不到位置要求的相符專案時,就會發生這種情況,因此會傳回較不精確的結果。 例如,如果找不到所要求位址的相符專案,則可能會傳回與 RoadBlock 實體類型的 相符代碼 UpHierarchy

Properties
ReverseGeocodingResultTypeEnum

在回應中指定您想要的實體類型。 只會傳回您指定的類型。 如果點無法對應至您指定的實體類型,回應中不會傳回任何位置資訊。 預設值是所有可能的實體。 從下列選項選取的實體類型逗號分隔清單。

  • 位址
  • 「鄰近地區」
  • PopulatedPlace
  • Postcode1
  • AdminDivision1
  • AdminDivision2
  • CountryRegion

這些實體類型會從最特定的實體排序到最不特定的實體。 找到多個實體類型的實體時,只會傳回最特定的實體。 例如,如果您將 Address 和 AdminDistrict1 指定為這兩種類型的實體類型和實體,則回應中只會傳回 Address 實體資訊。

UsageTypeEnum

最適合用於地理編碼點。 每個地理編碼點都會定義為 Route 點、 Display 點或兩者。 如果您要建立位置的路線,請使用 Route 點。 如果您要在地圖上顯示位置,請使用 Display 點。 例如,如果位置是一個駐留, Route 點可能會指定您可以用汽車進入的駐留,而 Display 某個點可能是指定駐留中心的點。

Address

結果的位址

名稱 類型 Description
addressLine

string

包含街地名和號碼的 AddressLine

adminDistricts

AdminDistricts[]

位址之國家或地區的細分名稱。 此元素通常被視為第一個訂單系統管理細分,但在某些情況下,它也會包含國家/地區、相依性或區域中的第二個、第三個或第四個順序細分。

countryRegion

CountryRegion

formattedAddress

string

格式化的 Address 屬性

intersection

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

如果信賴度設定為 High,則找到一或多個強式相符專案。 當適用時,多個 High 信賴比對會依重要性依順序排序。 例如,地標具有重要性,但位址並不重要。

如果要求包含位置或檢視,則排名可能會適當地變更。 例如,“Paris” 的位置查詢會傳回 “Paris, France” 和 “Paris, TX” 兩者皆具有 High 信賴度。 除非使用者位置指出用戶位於巴黎或非常接近巴黎、TX 或地圖檢視檢視,否則一律會因為重要性而優先排名,否則 TX 或地圖檢視檢視會指出使用者正在該區域中搜尋。

Low

string

Medium

string

在某些情況下,傳回的相符專案可能與要求中提供的資訊層級不同。 例如,要求可以指定地址資訊,而地理編碼服務可能只能比對郵遞區編碼。 在此情況下,如果地理編碼服務確信郵遞區編碼符合數據,則會將信賴度設定為 Medium ,並將比對碼設定為 UpHierarchy ,以指定它無法符合所有資訊,而且必須搜尋上階層。

如果查詢中的位置資訊模棱兩可,而且沒有其他資訊可排名位置 (例如使用者位置或位置) 的相對重要性,則信賴度會設定為 Medium。 例如,“148th Ave, Bellevue” 的位置查詢可能會傳回 “148th Ave SE” 和 “148th Ave NE” 兩者都具有 Medium 信賴度。

如果查詢中的位置資訊未提供足夠的資訊來地理編碼特定位置,可能會傳回較不精確的位置值,並將信賴度設定為 Medium。 例如,如果提供位址,但找不到房屋號碼的相符專案,可能會傳回具有 Roadblock 實體類型的地理編碼結果。

CountryRegion

名稱 類型 Description
ISO

string

國家/地區的 ISO

name

string

國家/地區的名稱

ErrorAdditionalInfo

資源管理錯誤其他資訊。

名稱 類型 Description
info

object

其他資訊。

type

string

其他信息類型。

ErrorDetail

錯誤詳細數據。

名稱 類型 Description
additionalInfo

ErrorAdditionalInfo[]

錯誤其他資訊。

code

string

錯誤碼。

details

ErrorDetail[]

錯誤詳細資料。

message

string

錯誤訊息。

target

string

錯誤目標。

ErrorResponse

錯誤回應

名稱 類型 Description
error

ErrorDetail

錯誤物件。

FeatureCollectionEnum

FeatureCollection 對象的類型必須是FeatureCollection。

名稱 類型 Description
FeatureCollection

string

FeaturesItem

名稱 類型 Description
bbox

number[]

周框方塊。 使用的投影 - EPSG:3857。 如需詳細資訊,請參閱 RFC 7946

geometry

GeoJsonPoint

有效的 GeoJSON Point 幾何類型。 如需詳細資訊,請參閱 RFC 7946

id

string

傳回之功能的標識碼

properties

Properties

type

FeatureTypeEnum

功能的類型必須是Feature。

FeatureTypeEnum

功能的類型必須是Feature。

名稱 類型 Description
Feature

string

GeocodePoints

地理編碼點的集合,其計算方式和建議的使用方式不同。

名稱 類型 Description
calculationMethod

CalculationMethodEnum

用來計算地理編碼點的方法。

geometry

GeoJsonPoint

有效的 GeoJSON Point 幾何類型。 如需詳細資訊 ,請參閱 RFC 7946

usageTypes

UsageTypeEnum[]

最適合用於地理編碼點。 每個地理編碼點都會定義為 Route 點、 Display 點或兩者。 如果您要建立位置的路線,請使用 Route 點。 如果您要在地圖上顯示位置,請使用 Display 點。 例如,如果位置是一個駐留, Route 點可能會指定您可以用汽車進入的駐留,而 Display 某個點可能是指定駐留中心的點。

GeocodingResponse

此物件是從成功的地理編碼呼叫傳回

名稱 類型 Description
features

FeaturesItem[]

nextLink

string

是傳回之功能下一頁的連結。 如果是最後一頁,則不會有此欄位。

type

FeatureCollectionEnum

FeatureCollection 對象的類型必須是FeatureCollection。

GeoJsonPoint

有效的 GeoJSON Point 幾何類型。 如需詳細資訊,請參閱 RFC 7946

名稱 類型 Description
bbox

number[]

周框方塊。 使用的投影 - EPSG:3857。 如需詳細資訊,請參閱 RFC 7946

coordinates

number[]

Position是具有兩個或多個元素的數位數位數位數位。 前兩個元素是 經度緯度,精確地以該順序排列。 高度/提高 許可權是選擇性的第三個元素。 如需詳細資訊,請參閱 RFC 7946

type string:

Point

指定 GeoJSON 類型。 必須是九個有效 GeoJSON 物件類型的其中一種: Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

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

Address

結果的位址

confidence

ConfidenceEnum

地理編碼位置結果為相符的信賴等級。 將此值與比對程式代碼搭配使用,以判斷比對的更完整資訊。

地理編碼位置的信賴度是以許多因素為基礎,包括地理編碼位置的相對重要性和使用者的位置。如果指定的話。

geocodePoints

GeocodePoints[]

地理編碼點的集合,其計算方式與建議的使用方式不同。

matchCodes

MatchCodesEnum[]

一或多個比對程式代碼值,代表回應中每個位置的地理編碼層級。

例如,具有相符代碼的 Good 地理編碼位置,表示 Ambiguous 找到多個地理位置資訊,而且地理編碼服務沒有搜尋上層來尋找相符專案。

同樣地,具有相符碼的 Ambiguous 地理編碼位置,表示 UpHierarchy 找不到符合所有提供的位置資訊,因此地理編碼服務必須搜尋上階層,並在該層級找到多個相符專案。 和 UpHierarchy 結果的Ambiguous範例是當您提供完整的地址資訊,但地理編碼服務找不到街地道址的相符專案,而是傳回多個 RoadBlock 值的資訊。

可能的值包括:

Good:位置只有一個相符專案,或所有傳回的相符專案都會被視為強式比對。 例如,紐約的查詢會傳回數個 Good 相符專案。

Ambiguous:位置是一組可能的相符專案。 例如,當您查詢街地道址 128 主要 St.時,回應可能會傳回 128 北主要 St. 和 128 南主要 St 的兩個位置。因為沒有足夠的資訊可判斷要選擇哪一個選項。

UpHierarchy:位置代表地理階層的上移。 當找不到位置要求的相符專案時,就會發生這種情況,因此會傳回較不精確的結果。 例如,如果找不到所要求位址的相符專案,則可能會傳回與 RoadBlock 實體類型的 相符程序代碼 UpHierarchy

type

string

值為下列其中之一:

  • 位址
  • 路障
  • RoadIntersection
  • 「鄰近地區」
  • PopulatedPlace
  • Postcode1
  • AdminDivision1
  • AdminDivision2
  • CountryRegion

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