Search - Get Reverse Geocoding
用于从经度和纬度坐标获取街道地址和位置信息。
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 (uri) |
Azure Maps 服务主机名。 Azure公有云使用 |
|
api-version
|
query | True |
string minLength: 1 |
用于此作的 API 版本。 |
|
coordinates
|
query | True |
number[] |
要反向地理编码的位置的坐标。 示例:&coordinates=lon,lat |
|
result
|
query |
指定响应中所需的实体类型。 仅返回指定的类型。 如果点无法映射到指定的实体类型,则响应中不会返回位置信息。 默认值是所有可能的实体。 从以下选项中选择的实体类型的逗号分隔列表。
这些实体类型从最具体的实体排序到最不具体的实体。 当找到多个实体类型的实体时,仅返回最具体的实体。 例如,如果将 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 |
应返回搜索结果的语言。 有关详细信息,请参阅 支持的语言。 |
响应
| 名称 | 类型 | 说明 |
|---|---|---|
| 200 OK |
请求已成功。 Media Types: "application/geo+json", "application/json" |
|
| Other Status Codes |
意外的错误响应。 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 资源账户或子资源的访问。 任何用户、组或服务主体都可以通过内置角色或由一个或多个对 Azure Maps REST API 的权限组成的自定义角色授予访问权限。
若要实现方案,建议查看
注释
- 此安全定义 要求 使用
x-ms-client-id标头来指示应用程序请求访问的 Azure Maps 资源。 这可以从 地图管理 API获取。 -
Authorization URL特定于 Azure 公有云实例。 主权云拥有独特的授权URL和Microsoft Entra ID配置。 - Azure 基于角色的访问控制是通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 从 Azure 管理平面 配置的。
- 使用 Azure Maps Web SDK 允许为多个用例设置基于应用程序的配置。
- 有关Microsoft标识平台的详细信息,请参阅 Microsoft标识平台概述。
类型:
oauth2
流向:
implicit
授权 URL:
https://login.microsoftonline.com/common/oauth2/authorize
作用域
| 名称 | 说明 |
|---|---|
| https://atlas.microsoft.com/.default |
subscription-key
这是在 Azure 门户中或使用 PowerShell、CLI、Azure SDK 或 REST API 创建 Azure Maps 帐户 时预配的共享密钥。
使用此密钥,任何应用程序都可以访问所有 REST API。 换句话说,此密钥可用作颁发密钥的帐户中的主密钥。
对于公开的应用程序,我们建议使用 机密客户端应用程序 方法来访问 Azure Maps REST API,以便安全地存储密钥。
类型:
apiKey
在:
header
SAS Token
这是一个共享访问签名令牌,它通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 通过 Azure 管理平面在 azure Maps 资源
使用此令牌,任何应用程序都有权使用 Azure 基于角色的访问控制进行访问,并精细控制特定令牌的过期、速率和区域。 换句话说,SAS 令牌可用于允许应用程序以比共享密钥更安全的方式控制访问。
对于公开的应用程序,建议在 映射帐户资源 上配置允许的源的特定列表,以限制呈现滥用并定期续订 SAS 令牌。
类型:
apiKey
在:
header
示例
Search point -122.138681, 47.630358
示例请求
GET https://atlas.microsoft.com/reverseGeocode?api-version=2026-01-01&coordinates=-122.138681,47.630358
示例响应
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 |
地理编码或自动补全建议位置的地址,解析成结构化字段。
稀疏是正常现象:只有已解析实体所提供的字段被填充。 例如, |
|
Address |
一个包含地址的行政分区。 例如,一个州、省或县。 作为父 |
|
Address |
包含地址的国家或地区,通过显示名称和ISO 3166-1 Alpha-2国家代码来标识。 在给定的回答中,任一栏都可以省略。 |
|
Azure. |
错误对象。 |
|
Azure. |
包含错误详细信息的响应。 |
|
Azure. |
包含有关错误的更具体信息的对象。 根据Azure REST API指南——https://aka.ms/AzureRestApiGuidelines#handling-errors。 |
|
Calculation |
用于计算地理编码点的方法。 |
|
Confidence |
地理编码位置结果匹配的置信度级别。 将该数值与匹配码结合使用,以获得更完整的比赛信息。 地理编码位置的置信度基于多种因素,包括地理编码位置的相对重要性以及用户位置(如有指定)。 |
|
Feature |
|
|
Features |
在 的 |
|
Features |
特征的有效载 |
|
Feature |
对象 |
|
Geocode |
一个位置的地理编码点:一个坐标加上描述该点如何计算 |
|
Geocoding |
成功响应体返回时为 |
|
Geo |
指定 |
|
Geo |
有效的 |
| Intersection |
地址的交叉细节,即两个或多个命名街道交汇处的地址。 只有当已解析实体为 时 |
|
Match |
匹配码值表示地理编码服务如何产生特定位置结果。
|
|
Reverse |
操作返回 |
|
Usage |
地理编码点的预期用途。 服务返回的地理码点包含一种或多种使用类型,指示客户端应用应如何使用该点:例如,在地图上显示位置,而不是将车辆引导到该点。 |
Address
地理编码或自动补全建议位置的地址,解析成结构化字段。
稀疏是正常现象:只有已解析实体所提供的字段被填充。 例如, streetName 和 streetNumber 只出现在街道级地址,且 intersection 仅出现在道路交叉口结果中。
| 名称 | 类型 | 说明 |
|---|---|---|
| addressLine |
string |
地址的第一行,通常是街道名称和编号。 例如, |
| adminDistricts |
包含地址的行政区划,按粗到优排序。 第一个条目通常是一阶细分(例如美国的一个州或加拿大的一个省);后续条目涵盖了国家、属地或地区定义的更细分(如索引1中的县)。 |
|
| countryRegion |
包含地址的国家或地区,包括显示名称和ISO 3166-1 Alpha-2国家代码。 |
|
| formattedAddress |
string |
完整地址以单一可读字符串的形式呈现,组件根据地址所在国家或地区的惯例连接。 示例: |
| intersection |
地址的交叉街道详细信息,当解析实体为a |
|
| locality |
string |
地址所属的地区通常是城市、城镇或村庄。 例如: |
| neighborhood |
string |
当确定某人时,指该区域内的命名社区。 |
| postalCode |
string |
地址的邮政编码,当定义为地址时。 示例: |
| streetName |
string |
地址的街道名称部分,当被解析的实体是街道级地址时。 示例: |
| streetNumber |
string |
当解决实体为街道级地址时,街道上的房屋或建筑编号。 示例: |
AddressAdminDistrictsItem
一个包含地址的行政分区。 例如,一个州、省或县。 作为父 Address.adminDistricts 数组中的一个条目返回,条目按粗到细排序。
| 名称 | 类型 | 说明 |
|---|---|---|
| name |
string |
该住宅区的全名。 例如, |
| shortName |
string |
当有定义时,是该分区名称的简称或缩写。 例如, |
AddressCountryRegion
包含地址的国家或地区,通过显示名称和ISO 3166-1 Alpha-2国家代码来标识。 在给定的回答中,任一栏都可以省略。
| 名称 | 类型 | 说明 |
|---|---|---|
| ISO |
string |
ISO 3166-1 Alpha-2国家代码,适用于该国家或地区。 例如, |
| name |
string |
显示国家或地区的名称。 例如, |
Azure.Core.Foundations.Error
错误对象。
| 名称 | 类型 | 说明 |
|---|---|---|
| code |
string |
服务器定义的错误代码集之一。 |
| details |
导致此报告错误的特定错误的详细信息数组。 |
|
| innererror |
包含与当前对象有关错误的更具体信息的对象。 |
|
| message |
string |
错误的人工可读表示形式。 |
| target |
string |
错误的目标。 |
Azure.Core.Foundations.ErrorResponse
包含错误详细信息的响应。
| 名称 | 类型 | 说明 |
|---|---|---|
| error |
错误对象。 |
Azure.Core.Foundations.InnerError
包含有关错误的更具体信息的对象。 根据Azure REST API指南——https://aka.ms/AzureRestApiGuidelines#handling-errors。
| 名称 | 类型 | 说明 |
|---|---|---|
| code |
string |
服务器定义的错误代码集之一。 |
| innererror |
内部错误。 |
CalculationMethodEnum
用于计算地理编码点的方法。
| 值 | 说明 |
|---|---|
| Interpolation |
使用插值将地理编码点与道路上的点进行匹配。 |
| InterpolationOffset |
地理编码点使用插值与道路上的点进行匹配,并使用额外的偏移量将点移动到街道一侧。 |
| Parcel |
地理编码点已与宗地中心匹配。 |
| Rooftop |
地理编码点与建筑物的屋顶匹配。 |
ConfidenceEnum
地理编码位置结果匹配的置信度级别。 将该数值与匹配码结合使用,以获得更完整的比赛信息。
地理编码位置的置信度基于多种因素,包括地理编码位置的相对重要性以及用户位置(如有指定)。
| 值 | 说明 |
|---|---|
| High |
如果置信度设置为 如果请求包含地点或视图,排名可能会相应调整。 例如,查询“Paris”时,会有信心地返回“Paris, France”和“Paris, TX” |
| Medium |
在某些情况下,返回的匹配项可能与请求中提供的信息不在同一级别。 例如,请求可以指定地址信息,而地理编码服务可能只能匹配邮政编码。 在这种情况下,如果地理编码服务有信心邮政编码与数据匹配,则置信度设为, 如果查询中的位置信息不明确,并且没有其他信息来对位置进行排名(例如用户位置或位置的相对重要性),则置信度设置为 如果查询中的位置信息未提供足够的信息来对特定位置进行地理编码,则可能会返回不太精确的位置值,并将置信度设置为 |
| Low |
对比赛信心低。 |
FeatureCollectionEnum
GeoJSON用于前向地理编码、反向地理编码和自动补全操作(包括其批处理变体)成功响应的对象类型。 唯一的值是 FeatureCollection,按照 RFC 7946 的定义。
Get Polygon 是唯一的例外:其响应根是 GeoJSON Feature,参见 FeatureTypeEnum。
| 值 | 说明 |
|---|---|
| FeatureCollection |
对象 |
FeaturesItem
在 的GeocodingResponse数组中features,一个与对象形状相符GeoJSON Feature的单一元素。
表示一个地理编码位置:上的properties结构化数据,代表性坐标,geometry以及一个可选的边界框。bbox
| 名称 | 类型 | 说明 |
|---|---|---|
| bbox |
number[] (double) |
包含该特征几何形状的最小轴对齐矩形,按WGS 84经纬度顺序排列。 按照 |
| geometry |
主 |
|
| id |
string |
功能可选择的服务分配标识符(如果有的话)。 |
| properties |
关于地理编码位置的结构化数据,包括实体类型、匹配质量指标、地址组成部分以及一个或多个地理编码点。 |
|
| type |
对象 |
FeaturesItemProperties
特征的有效载GeocodingResponse荷。properties 携带地理编码位置的实体类型和匹配质量指示器、解析后的地址组件,以及一个或多个将位置固定到特定坐标的地理编码点。
| 名称 | 类型 | 说明 |
|---|---|---|
| address |
地理编码位置的地址,解析为结构化字段,如地区、邮政编码、国家/地区,以及(如有)街道名称和编号。 |
|
| confidence |
地理编码位置与请求的匹配度如何? 结合使用, |
|
| geocodePoints |
一个或多个位置的地理编码点,每个点标注其来源 |
|
| matchCodes |
地理编码服务如何相对于查询产生该结果:在请求的具体性 |
|
| type |
string |
地理编码位置所解析的实体类型。 其中一个: |
FeatureTypeEnum
对象 GeoJSON 类型 Feature 。 在响应数组FeatureCollection内为每个条目features打标签(地理编码、反向地理编码、自动补全),并出现在响应的Get Polygon根节点。 唯一的值是 Feature,按照 RFC 7946 的定义。
| 值 | 说明 |
|---|---|
| Feature |
对象 |
GeocodePointsItem
一个位置的地理编码点:一个坐标加上描述该点如何计算calculationMethod()及其最适合用途的元数据(usageTypes)。 单个功能通常单独返回 Display 点数, Route 方便呼叫者选择最适合任务的。
| 名称 | 类型 | 说明 |
|---|---|---|
| calculationMethod |
积分是如何计算的。 例如,将画面切入建筑物屋顶或沿道路中心线插值。 请参见 |
|
| geometry |
该地理码点的坐标为 |
|
| usageTypes |
地理 |
GeocodingResponse
成功响应体返回时为 Get GeocodingGet Reverse Geocoding和 ,批次-项目成功形状也 GeocodingBatchResponse.batchItems在 内携带。
编码为 ,GeoJSON FeatureCollection其features数组中每个地理编码位置包含一个。Feature
| 名称 | 类型 | 说明 |
|---|---|---|
| features |
查询返回的对象数组 |
|
| nextLink |
string |
包含如果回复有分页,可以获取下一页的结果。 当响应量过大无法一次性返回时,这非常有用,允许用户浏览多页结果。 |
| type |
|
GeoJsonObjectType
指定 GeoJSON 类型。 必须是九种有效的 GeoJSON 对象类型之一 - Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。
| 值 | 说明 |
|---|---|
| Point |
|
| MultiPoint |
|
| LineString |
|
| MultiLineString |
|
| Polygon |
|
| MultiPolygon |
|
| GeometryCollection |
|
| Feature |
|
| FeatureCollection |
|
GeoJsonPoint
有效的 GeoJSON Point 几何图形类型。 有关详细信息,请参阅 RFC 7946。
| 名称 | 类型 | 说明 |
|---|---|---|
| bbox |
number[] (double) |
边界框。 使用的投影 - EPSG:3857。 有关详细信息,请参阅 RFC 7946。 |
| coordinates |
number[] (double) |
|
| type |
string:
Point |
指定 |
Intersection
地址的交叉细节,即两个或多个命名街道交汇处的地址。 只有当已解析实体为 时 RoadIntersection才填充; Address.intersection 否则父实体则省略。
| 名称 | 类型 | 说明 |
|---|---|---|
| baseStreet |
string |
交叉口的主要街道——通常是地址编号所指的街道。 |
| displayName |
string |
一个人类可读的交叉口名称,用于连接交叉街道,例如 |
| intersectionType |
string |
一个简短的标签,描述了交汇的形状。 例如,区分平面交叉路口与桥梁或立交桥等立体交叉口。 |
| secondaryStreet1 |
string |
第一个交叉口的 |
| secondaryStreet2 |
string |
当有交叉口时,第二个交叉口。 仅在三条或更多街道交叉口居住。 |
MatchCodesEnum
匹配码值表示地理编码服务如何产生特定位置结果。
matchCodes特征的字段是这些数值的数组;将它们与 confidence 和 type 结合以评估匹配质量。
| 值 | 说明 |
|---|---|
| Good |
地理编码服务在未扩大查询范围的情况下生成了候选对象:结果在请求的具体性上与查询匹配。 |
| Ambiguous |
地点是一组可能匹配中的一个。 例如,当查询街道地址“128 Main St.”时,回答可能会返回“128 North Main St.”和“128 South Main St.”两个地点,因为信息不足以决定选择哪一个选项。 |
| UpHierarchy |
该位置代表地理层级的上升。 如果未找到位置请求的匹配项,则会发生这种情况,因此会返回不太精确的结果。 |
ReverseGeocodingResultTypeEnum
操作返回 Get Reverse Geocoding 的实体类型。 以查询参数中的 resultTypes 一个或多个值提供,以限制响应对特定类型的位置;当参数被省略时,所有实体类型均可满足条件。 当多个类型的实体匹配一个坐标时,只返回最具体的。 从最具体到最不具体的顺序列出:Address, Neighborhood, PopulatedPlace, AdminDivision1Postcode1AdminDivision2, , CountryRegion。
| 值 | 说明 |
|---|---|
| Address |
一个具体的街道地址。 |
| Neighborhood |
在一个人口稠密的地方内,通常具有非正式或文化界限的区域。 |
| PopulatedPlace |
人类住区的集中区域,例如城市、城镇或村庄。 |
| Postcode1 |
最小的邮政编码类别,如邮政编码。 |
| AdminDivision1 |
第一级行政层级是在国家/地区内,比如州或省。 |
| AdminDivision2 |
国家/地区内的第二级行政层级,如县。 |
| CountryRegion |
一个国家或地区。 |
UsageTypeEnum
地理编码点的预期用途。 服务返回的地理码点包含一种或多种使用类型,指示客户端应用应如何使用该点:例如,在地图上显示位置,而不是将车辆引导到该点。
| 值 | 说明 |
|---|---|
| Display |
地理码点适合在地图上显示位置。 对于具有非平凡范围的特征(如公园或建筑物),该 |
| Route |
地理编码点适合作为路线的目的地。 对于范围非平凡的特征(如公园或建筑物),点 |