你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Search - Get Reverse Geocoding

服务:: Maps

API 版本:: 2026-01-01

用于从经度和纬度坐标获取街道地址和位置信息。
Get Reverse Geocoding API 是一个 HTTP GET 请求，用于将坐标（例如：37.786505、-122.3862）转换为人类可理解的街道地址。可用于跟踪从设备或资产接收 GPS 源并想要知道与坐标关联的地址的应用程序。此终结点将返回给定坐标的地址信息。

GET {endpoint}/reverseGeocode?api-version=2026-01-01&coordinates={coordinates}

具有可选参数:

GET {endpoint}/reverseGeocode?api-version=2026-01-01&coordinates={coordinates}&resultTypes={resultTypes}&view={view}

URI 参数

名称	在	必需	类型	说明
endpoint	path	True	string
api-version	query	True	string minLength: 1	用于此作的 API 版本。
coordinates	query	True	number[]	要反向地理编码的位置的坐标。示例：&coordinates=lon，lat
resultTypes	query		ReverseGeocodingResultTypeEnum[]	指定响应中所需的实体类型。仅返回指定的类型。如果点无法映射到指定的实体类型，则响应中不会返回位置信息。默认值是所有可能的实体。从以下选项中选择的实体类型的逗号分隔列表。地址附近 PopulatedPlace Postcode1 AdminDivision1 AdminDivision2 国家/地区这些实体类型从最具体的实体排序到最不具体的实体。当找到多个实体类型的实体时，仅返回最具体的实体。例如，如果将 Address 和 AdminDistrict1 指定为两种类型的实体类型和实体，则响应中仅返回 Address 实体信息。
view	query		string	一个字符串，表示 ISO 3166-1 Alpha-2 区域/国家/地区代码。这将更改地缘政治争议的边框和标签，使其与指定的用户区域保持一致。默认情况下，“视图”参数设置为“自动”，即使你未在请求中定义它也是如此。有关详细信息，请参阅支持的视图，并查看可用的视图。

请求头

名称	必需	类型	说明
x-ms-client-id		string	指定哪个账户用于与 Azure AD 安全模型结合使用。它代表 Azure Maps 账户的唯一 ID，可以从 Azure Maps 管理平面账户 API 中获取。有关在Azure Maps中使用Microsoft Entra ID安全的更多信息，请参见管理认证在Azure Maps。
Accept-Language		string	应返回搜索结果的语言。有关详细信息，请参阅支持的语言。

名称

必需

类型

说明

x-ms-client-id

string

指定哪个账户用于与 Azure AD 安全模型结合使用。它代表 Azure Maps 账户的唯一 ID，可以从 Azure Maps 管理平面账户 API 中获取。有关在Azure Maps中使用Microsoft Entra ID安全的更多信息，请参见管理认证在Azure Maps。

Accept-Language

string

应返回搜索结果的语言。

有关详细信息，请参阅支持的语言。

响应

名称	类型	说明
200 OK	GeocodingResponse	请求已成功。 Media Types: "application/geo+json", "application/json"
Other Status Codes	Azure.Core.Foundations.ErrorResponse	意外的错误响应。 Media Types: "application/geo+json", "application/json" 标头 x-ms-error-code: string

名称

类型

说明

200 OK

GeocodingResponse

请求已成功。

Media Types: "application/geo+json", "application/json"

Other Status Codes

Azure.Core.Foundations.ErrorResponse

意外的错误响应。

Media Types: "application/geo+json", "application/json"

标头

x-ms-error-code: string

安全性

AadToken

这些是Microsoft Entra OAuth 2.0流量。当与Azure基于角色的访问控制配合使用时，可以用来控制对Azure Maps REST API的访问。 Azure 基于角色的访问控制用于指定对一个或多个 Azure Maps 资源账户或子资源的访问。任何用户、组或服务主体都可以通过内置角色或由一个或多个 REST API 权限组成的自定义角色获得访问权限，Azure Maps\n\n要实现场景，建议查看 authentication concepts。总之，该安全定义为通过能够对特定API和作用域进行访问控制的对象建模应用提供了解决方案。\n\n#### 注释\n* 此安全定义要求使用x-ms-client-id头来指示应用程序请求访问的资源Azure Maps。这可通过Maps管理API获取。\n* \nAuthorization URL 是针对Azure公有云实例特有的。主权云拥有独特的授权URL和Microsoft Entra ID配置。 \n* \nAzure基于角色的访问控制通过Azure门户、PowerShell、CLI、Azure SDK或REST API从Azure管理层配置。\n* \nAzure MapsWeb SDK 允许基于配置的应用设置，适用于多种用例。\n* 有关Microsoft 标识平台的更多信息，请参见 Microsoft 标识平台概览。

类型: oauth2
流向: implicit
授权 URL: https://login.microsoftonline.com/common/oauth2/authorize

作用域

名称	说明
https://atlas.microsoft.com/.default

subscription-key

这是一个共享密钥，当你在Azure门户中创建Azure Maps账户，或使用 PowerShell、CLI、Azure SDK 或 REST API 时，会被配置。\n\n 有了这个密钥，任何应用程序都可以访问所有 REST API。换句话说，这个密钥可以作为发行账户的主密钥使用。\n\n 对于公开暴露的应用，我们建议采用confidential客户端应用方法访问Azure Maps REST API，以便你的密钥能够安全存储。

类型: apiKey
在: header

SAS Token

这是一个共享访问签名令牌，通过Azure Maps资源的List SAS操作，通过Azure门户、PowerShell、CLI、Azure SDK或REST API在Azure管理层创建。\n\n 使用此令牌，任何应用程序都被授权使用Azure访问基于角色的访问控制和对特定令牌的到期时间、速率和使用区域的细粒度控制。换句话说，SAS 令牌可以用来让应用程序以比共享密钥更安全的方式控制访问。\n\n 对于公开暴露的应用，我们建议在 Map账户资源上配置一个具体的允许来源列表，以减少渲染滥用，并定期续签SAS令牌。

类型: apiKey
在: header

示例

Search point -122.138681, 47.630358

示例请求

HTTP

GET {endpoint}/reverseGeocode?api-version=2026-01-01&coordinates=-122.138681,47.630358

示例响应

状态代码:: 200

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "address": {
          "countryRegion": {
            "name": "United States"
          },
          "adminDistricts": [
            {
              "name": "Washington",
              "shortName": "WA"
            },
            {
              "name": "King County",
              "shortName": "King Co."
            }
          ],
          "formattedAddress": "15127 NE 24th St, Redmond, Washington 98052",
          "streetName": "NE 24th St",
          "streetNumber": "15127",
          "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
      ]
    }
  ]
}

定义

名称	说明
Address	结果的地址
AddressAdminDistrictsItem	地址所在国家或地区的细分名称。
AddressCountryRegion	国家或地区及其名称和 ISO 代码。
Azure.Core.Foundations.Error	错误对象。
Azure.Core.Foundations.ErrorResponse	包含错误详细信息的响应。
Azure.Core.Foundations.InnerError	包含有关错误的更具体信息的对象。根据Azure REST API指南——https://aka.ms/AzureRestApiGuidelines#handling-errors。
CalculationMethodEnum	用于计算地理编码点的方法。
ConfidenceEnum	地理编码位置结果匹配的置信度级别。将此值与匹配代码一起使用，以确定有关匹配的更完整信息。地理编码位置的置信度基于许多因素，包括地理编码位置和用户位置（如果指定）的相对重要性。
FeatureCollectionEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 `FeatureCollection`。有关详细信息，请参阅 RFC 7946。
FeaturesItem	一个特征对象。
FeaturesItemProperties	特征的性质。
FeatureTypeEnum	特征的类型必须是功能。
GeocodePointsItem	一个地理编码点。
GeocodingResponse	此对象是从成功的地理编码调用返回的
GeoJsonObjectType	指定 `GeoJSON` 类型。必须是九种有效的 GeoJSON 对象类型之一 - Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。
GeoJsonPoint	有效的 `GeoJSON Point` 几何图形类型。有关详细信息，请参阅 RFC 7946。
Intersection	结果的地址。
MatchCodesEnum	一个枚举，代表比赛代码。
ReverseGeocodingResultTypeEnum	一个表示反向地理编码结果类型的枚举。
UsageTypeEnum	一个代表使用类型的枚举。

Address

对象

结果的地址

名称	类型	说明
addressLine	string	包含街道名称和街道号码的地址行
adminDistricts	AddressAdminDistrictsItem[]	地址所在国家或地区的细分名称。此元素通常被视为第一个顺序管理细分，但在某些情况下，它还包含国家/地区、依赖项或区域的第二、第三或第四个顺序细分。
countryRegion	AddressCountryRegion	国家或地区及其名称和 ISO 代码。
formattedAddress	string	格式化地址属性
intersection	Intersection	结果的地址。
locality	string	Locality 属性
neighborhood	string	邻里物业
postalCode	string	邮政编码属性
streetName	string	formattedAddress 中的街道名称
streetNumber	string	街道上的号码（如果可用），来自 formattedAddress

AddressAdminDistrictsItem

对象

地址所在国家或地区的细分名称。

名称	类型	说明
name	string	相应 adminDistrict 字段的名称，对于 adminDistrict[0]，这可能是州的完整名称，例如华盛顿，对于 adminDistrict[1]，这可能是该县的全名
shortName	string	相应 adminDistrict 字段的短名称，对于 adminDistrict[0]，这可能是州名称的短名称，例如 WA，对于 adminDistrict[1]，这可能是县的短名称

AddressCountryRegion

对象

国家或地区及其名称和 ISO 代码。

名称	类型	说明
ISO	string	国家/地区的 ISO
name	string	国家/地区的名称

Azure.Core.Foundations.Error

对象

错误对象。

名称	类型	说明
code	string	服务器定义的错误代码集之一。
details	Azure.Core.Foundations.Error[]	导致此报告错误的特定错误的详细信息数组。
innererror	Azure.Core.Foundations.InnerError	包含与当前对象有关错误的更具体信息的对象。
message	string	错误的人工可读表示形式。
target	string	错误的目标。

Azure.Core.Foundations.ErrorResponse

对象

包含错误详细信息的响应。

名称	类型	说明
error	Azure.Core.Foundations.Error	错误对象。

Azure.Core.Foundations.InnerError

对象

包含有关错误的更具体信息的对象。根据Azure REST API指南——https://aka.ms/AzureRestApiGuidelines#handling-errors。

名称	类型	说明
code	string	服务器定义的错误代码集之一。
innererror	Azure.Core.Foundations.InnerError	内部错误。

CalculationMethodEnum

枚举

用于计算地理编码点的方法。

值	说明
Interpolation	使用插值将地理编码点与道路上的点进行匹配。
InterpolationOffset	地理编码点使用插值与道路上的点进行匹配，并使用额外的偏移量将点移动到街道一侧。
Parcel	地理编码点已与宗地中心匹配。
Rooftop	地理编码点与建筑物的屋顶匹配。

ConfidenceEnum

枚举

地理编码位置结果匹配的置信度级别。将此值与匹配代码一起使用，以确定有关匹配的更完整信息。

地理编码位置的置信度基于许多因素，包括地理编码位置和用户位置（如果指定）的相对重要性。

值说明

High

值	说明
High	如果置信度设置为 `High`，则找到了一个或多个强匹配项。多个置信度匹配按 `High` 重要性排名排序（如果适用）。例如，地标具有重要性，但地址不重要。如果请求包含位置或视图，则排名可能会相应更改。例如，对“Paris”的位置查询会可靠地 `High` 返回“Paris， France”和“Paris， TX”。由于重要性，“法国巴黎”始终排在第一位，除非用户位置表明用户位于或非常靠近德克萨斯州巴黎，或者地图视图表明用户正在该区域进行搜索。
Medium	在某些情况下，返回的匹配项可能与请求中提供的信息不在同一级别。例如，请求可以指定地址信息，而地理编码服务可能只能匹配邮政编码。在这种情况下，如果地理编码服务具有邮政编码与数据匹配的置信度，则置信度设置为， `Medium` 匹配代码设置为， `UpHierarchy` 以指定它无法匹配所有信息，并且必须向上搜索层次结构。如果查询中的位置信息不明确，并且没有其他信息来对位置进行排名（例如用户位置或位置的相对重要性），则置信度设置为 `Medium`。例如，对“148th Ave， Bellevue”的位置查询可能会可靠地 `Medium` 返回“148th Ave SE”和“148th Ave NE”。如果查询中的位置信息未提供足够的信息来对特定位置进行地理编码，则可能会返回不太精确的位置值，并将置信度设置为 `Medium`。例如，如果提供了地址，但未找到门牌号的匹配项，则可能会返回具有路障实体类型的地理编码结果。
Low	低

如果置信度设置为 High，则找到了一个或多个强匹配项。多个置信度匹配按 High 重要性排名排序（如果适用）。例如，地标具有重要性，但地址不重要。

如果请求包含位置或视图，则排名可能会相应更改。例如，对“Paris”的位置查询会可靠地 High 返回“Paris， France”和“Paris， TX”。由于重要性，“法国巴黎”始终排在第一位，除非用户位置表明用户位于或非常靠近德克萨斯州巴黎，或者地图视图表明用户正在该区域进行搜索。

Medium

在某些情况下，返回的匹配项可能与请求中提供的信息不在同一级别。例如，请求可以指定地址信息，而地理编码服务可能只能匹配邮政编码。在这种情况下，如果地理编码服务具有邮政编码与数据匹配的置信度，则置信度设置为， Medium 匹配代码设置为， UpHierarchy 以指定它无法匹配所有信息，并且必须向上搜索层次结构。

如果查询中的位置信息不明确，并且没有其他信息来对位置进行排名（例如用户位置或位置的相对重要性），则置信度设置为 Medium。例如，对“148th Ave， Bellevue”的位置查询可能会可靠地 Medium 返回“148th Ave SE”和“148th Ave NE”。

如果查询中的位置信息未提供足够的信息来对特定位置进行地理编码，则可能会返回不太精确的位置值，并将置信度设置为 Medium。例如，如果提供了地址，但未找到门牌号的匹配项，则可能会返回具有路障实体类型的地理编码结果。

Low

低

FeatureCollectionEnum

枚举

指定 GeoJSON 类型。唯一支持的对象类型是 FeatureCollection。有关详细信息，请参阅 RFC 7946。

值	说明
FeatureCollection	指定 `GeoJSONFeatureCollection` 对象类型。

FeaturesItem

对象

一个特征对象。

名称	类型	说明
bbox	number[] (double)	边界框。使用的投影 - EPSG：3857。有关详细信息，请参阅 RFC 7946。
geometry	GeoJsonPoint	有效的 `GeoJSON Point` 几何图形类型。有关详细信息，请参阅 RFC 7946。
id	string	返回的功能的 ID
properties	FeaturesItemProperties	特征的性质。
type	FeatureTypeEnum	特征的类型必须是功能。

FeaturesItemProperties

对象

特征的性质。

名称	类型	说明
address	Address	结果的地址
confidence	ConfidenceEnum	地理编码位置结果匹配的置信度级别。将此值与匹配代码一起使用，以确定有关匹配的更完整信息。地理编码位置的置信度基于许多因素，包括地理编码位置和用户位置（如果指定）的相对重要性。
geocodePoints	GeocodePointsItem[]	一组地理编码点，这些点的计算方式及其建议的使用方式不同。
matchCodes	MatchCodesEnum[]	一个或多个匹配代码值，表示响应中每个位置的地理编码级别。例如，具有匹配代码的地理编码位置 `Good` 和 `Ambiguous` 意味着为位置信息找到了多个地理编码位置，并且地理编码服务没有搜索向上层次结构来查找匹配项。同样，具有匹配代码的地理编码位置 `Ambiguous` 和 `UpHierarchy` 意味着找不到与提供的所有位置信息匹配的地理编码位置，因此地理编码服务必须搜索层次结构并在该级别找到多个匹配项。 `Ambiguous` 和 `UpHierarchy` 结果的一个示例是提供完整的地址信息，但地理编码服务找不到街道地址的匹配项，而是返回多个 RoadBlock 值的信息。可能的值为： `Good`：该位置只有一个匹配项或所有返回的匹配项被视为强匹配项。例如，纽约的查询返回多个 Good 匹配项。 `Ambiguous`：位置是一组可能的匹配项之一。例如，在查询街道地址 128 Main St.时，响应可能会返回 128 北主街和 128 南主街的两个位置，因为没有足够的信息来确定要选择的选项。 `UpHierarchy`：位置表示向上移动的地理层次结构。如果未找到位置请求的匹配项，则会发生这种情况，因此会返回不太精确的结果。例如，如果找不到所请求地址的匹配项，则可能会返回具有 RoadBlock 实体类型的 `UpHierarchy` 匹配代码。
type	string	其中之一：* 地址 * 路障 * 路口 * 社区 * 有人居住的地方 * 邮政编码1 * 行政区1 * 行政区2 * 国家地区

FeatureTypeEnum

枚举

特征的类型必须是功能。

值	说明
Feature	指定功能对象类型 `GeoJSON`。

GeocodePointsItem

对象

一个地理编码点。

名称	类型	说明
calculationMethod	CalculationMethodEnum	用于计算地理编码点的方法。
geometry	GeoJsonPoint	有效的 `GeoJSON Point` 几何图形类型。有关详细信息，请参阅 RFC 7946。
usageTypes	UsageTypeEnum[]	最适合地理编码点。每个地理编码点都定义为 `Route` 点、`Display` 点或两者。如果要创建指向位置的路由，请使用 `Route` 点。如果在地图上显示位置，请使用 `Display` 点。例如，如果位置是公园，`Route` 点可以指定公园的入口，可以使用汽车进入，而 `Display` 点可能是指定公园中心点。

GeocodingResponse

对象

此对象是从成功的地理编码调用返回的

名称	类型	说明
features	FeaturesItem[]	查询结果显示了一系列特征。
nextLink	string	该链接指向返回的功能的下一页。如果是最后一页，则不显示此字段。
type	FeatureCollectionEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 `FeatureCollection`。有关详细信息，请参阅 RFC 7946。

GeoJsonObjectType

枚举

指定 GeoJSON 类型。必须是九种有效的 GeoJSON 对象类型之一 - Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

值	说明
Point	`GeoJSON Point` 几何图形。
MultiPoint	`GeoJSON MultiPoint` 几何图形。
LineString	`GeoJSON LineString` 几何图形。
MultiLineString	`GeoJSON MultiLineString` 几何图形。
Polygon	`GeoJSON Polygon` 几何图形。
MultiPolygon	`GeoJSON MultiPolygon` 几何图形。
GeometryCollection	`GeoJSON GeometryCollection` 几何图形。
Feature	`GeoJSON Feature` 对象。
FeatureCollection	`GeoJSON FeatureCollection` 对象。

GeoJsonPoint

对象

有效的 GeoJSON Point 几何图形类型。有关详细信息，请参阅 RFC 7946。

名称	类型	说明
bbox	number[] (double)	边界框。使用的投影 - EPSG：3857。有关详细信息，请参阅 RFC 7946。
coordinates	number[] (double)	`Position` 是包含两个或多个元素的数字数组。前两个元素经度和纬度，精确按顺序排列。海拔/海拔是可选的第三个元素。有关详细信息，请参阅 RFC 7946。
type	string: Point	指定 `GeoJSON` 类型。必须是九种有效的 GeoJSON 对象类型之一 - Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

Intersection

对象

结果的地址。

名称	类型	说明
baseStreet	string	该位置的主要街道。
displayName	string	交集的完整名称。
intersectionType	string	交集的类型。
secondaryStreet1	string	第一条相交的街道。
secondaryStreet2	string	如果有，第二条相交的街道。

MatchCodesEnum

枚举

一个枚举，代表比赛代码。

值	说明
Good	好
Ambiguous	不明确
UpHierarchy	上层结构

ReverseGeocodingResultTypeEnum

枚举

一个表示反向地理编码结果类型的枚举。

值	说明
Address	地址
Neighborhood	附近
PopulatedPlace	PopulatedPlace
Postcode1	Postcode1
AdminDivision1	AdminDivision1
AdminDivision2	AdminDivision2
CountryRegion	国家/地区

UsageTypeEnum

枚举

一个代表使用类型的枚举。

值	说明
Display	显示
Route	路线