你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
Search - Get Geocoding Batch
使用 在单个请求中将一批查询发送到 地理编码 API。
API Get Geocoding Batch
是一个 HTTP POST
请求,在单个请求中向地理编码 API 发送最多 100 个查询批。
提交同步批处理请求
对于轻型批处理请求,建议使用同步 API。 当服务收到请求时,它将在计算批处理项后立即响应,并且以后无法检索结果。 如果请求花费的时间超过 60 秒,同步 API 将返回超时错误 (408 响应) 。 此 API 的批处理项数限制为 100 个。
POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01
批处理请求的 POST 正文
若要发送地理编码查询,你将使用请求POST
,其中请求正文将包含格式的batchItems
json
数组,Content-Type
并且标头将设置为 application/json
。 下面是包含 2 个 地理编码 查询的请求正文示例:
{
"batchItems": [
{
"addressLine": "One, Microsoft Way, Redmond, WA 98052",
"top": 2
},
{
"addressLine": "Pike Pl",
"adminDistrict": "WA",
"locality": "Seattle",
"top": 3
}
]
}
地理编码 batchItem 对象可以接受任何受支持的地理编码URI 参数。
该批应至少包含 1 个 查询。
批处理响应模型
批处理响应包含一个 summary
组件,该组件指示 totalRequests
是原始批处理请求的一部分, successfulRequests
即已成功执行的查询。 批处理响应还包括一个 batchItems
数组,其中包含批处理请求中每个查询的响应。
batchItems
将包含结果的顺序与原始查询在批处理请求中的发送顺序完全相同。 每个项都具有以下类型之一:
GeocodingResponse
- 如果查询成功完成。Error
- 如果查询失败。 在本例中,响应将包含code
和message
。
POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01
URI 参数
名称 | 在 | 必需 | 类型 | 说明 |
---|---|---|---|---|
api-version
|
query | True |
string |
Azure Maps API 的版本号。 |
请求头
名称 | 必需 | 类型 | 说明 |
---|---|---|---|
x-ms-client-id |
string |
指定要与 Azure AD 安全模型一起使用的帐户。 它表示 Azure Maps 帐户的唯一 ID,可以从 Azure Maps 管理平面帐户 API 检索。 若要在 Azure Maps 中使用 Azure AD 安全性,请参阅以下 文章 以获取指导。 |
|
Accept-Language |
string |
应返回搜索结果的语言。 有关详细信息,请参阅 支持的语言 。 |
请求正文
名称 | 类型 | 说明 |
---|---|---|
batchItems |
要处理的查询列表。 |
响应
名称 | 类型 | 说明 |
---|---|---|
200 OK |
确定 |
|
Other Status Codes |
发生了意外错误。 |
安全性
AADToken
这些是 Microsoft Entra OAuth 2.0 流。 与 Azure 基于角色的访问控制 配对后,它可用于控制对 Azure Maps REST API 的访问。 Azure 基于角色的访问控制用于指定对一个或多个 Azure Maps 资源帐户或子资源的访问权限。 可以通过内置角色或由 Azure Maps REST API 的一个或多个权限组成的自定义角色授予任何用户、组或服务主体的访问权限。
若要实现方案,建议查看 身份验证概念。 总之,此安全定义提供了一个解决方案,用于通过能够对特定 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 | https://atlas.microsoft.com/.default |
subscription-key
这是在通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 通过 Azure 管理平面创建 Azure Maps 资源 时预配的共享密钥。
使用此密钥,任何应用程序都有权访问所有 REST API。 换句话说,这些密钥当前可以视为颁发它们的帐户的主密钥。
对于公开的应用程序,我们建议使用 Azure Maps REST API 的服务器到服务器访问权限,以便安全地存储此密钥。
类型:
apiKey
在:
header
SAS Token
这是通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 通过 Azure 管理平面通过 Azure Maps 资源 上的列出 SAS 操作创建的共享访问签名令牌。
使用此令牌,任何应用程序都有权使用 Azure 基于角色的访问控制进行访问,并精细控制特定令牌的过期、速率和区域 () 。 换句话说,SAS 令牌可用于允许应用程序以比共享密钥更安全的方式控制访问。
对于公开的应用程序,我们建议在 Map 帐户资源 上配置允许的来源的特定列表,以限制呈现滥用,并定期续订 SAS 令牌。
类型:
apiKey
在:
header
示例
A Geocoding Batch API call containing 2 Geocoding queries
示例请求
POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01
{
"batchItems": [
{
"addressLine": "One, Microsoft Way, Redmond, WA 98052",
"top": 2,
"optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
},
{
"addressLine": "Pike Pl",
"adminDistrict": "WA",
"locality": "Seattle",
"top": 3
}
]
}
示例响应
{
"summary": {
"successfulRequests": 1,
"totalRequests": 2
},
"batchItems": [
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"type": "Address",
"confidence": "High",
"matchCodes": [
"Good"
],
"address": {
"locality": "Redmond",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King"
}
],
"countryRegion": {
"ISO": "US",
"name": "United States"
},
"postalCode": "98052",
"formattedAddress": "1 Microsoft Way, Redmond, WA 98052",
"addressLine": "1 Microsoft Way"
},
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.128275,
47.639429
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display",
"Route"
]
},
{
"geometry": {
"type": "Point",
"coordinates": [
-122.127028,
47.638545
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-122.128275,
47.639429
]
},
"bbox": [
-122.1359181505759,
47.63556628242932,
-122.1206318494241,
47.643291717570676
]
}
]
},
{
"error": {
"code": "Conflicting Parameters",
"message": "When 'query' is present, only the following parameters are valid: 'bbox, location, view, top'. 'addressLine' was passed"
}
}
]
}
定义
名称 | 说明 |
---|---|
Address |
结果的地址 |
Admin |
地址所在国家或地区的细分名称。 此元素通常被视为第一个顺序管理细分,但在某些情况下,它还包含国家/地区、依赖项或区域中的第二、第三或第四个顺序细分。 |
Calculation |
用于计算地理编码点的方法。 |
Confidence |
地理编码位置结果为匹配的置信度级别。 将此值与匹配代码一起使用,以确定有关匹配的更完整信息。 地理编码位置的置信度基于许多因素,包括地理编码位置和用户位置的相对重要性(如果指定)。 |
Country |
|
Error |
资源管理错误附加信息。 |
Error |
错误详细信息。 |
Error |
错误响应 |
Feature |
FeatureCollection 对象的类型必须为 FeatureCollection。 |
Features |
|
Feature |
功能的类型必须为“功能”。 |
Geocode |
地理编码点的集合,它们在计算方式及其建议用途方面有所不同。 |
Geocoding |
要处理的地址地理编码查询/请求的列表。 该列表最多可以包含 100 个查询,并且必须至少包含 1 个查询。 |
Geocoding |
Batch Query 对象 |
Geocoding |
此对象是从成功的地理编码 Batch 服务调用返回的。 |
Geocoding |
|
Geo |
有效的 |
Intersection |
结果的地址。 |
Match |
一个或多个表示响应中每个位置的地理编码级别的匹配代码值。 例如,匹配代码为 和 同样,匹配代码为 和 可能的值为:
|
Properties | |
Summary |
批处理请求摘要 |
Usage |
地理编码点的最佳用途。
每个地理编码点都定义为一个 |
Address
结果的地址
名称 | 类型 | 说明 |
---|---|---|
addressLine |
string |
包含街道名称和编号的 AddressLine |
adminDistricts |
地址所在国家或地区的细分名称。 此元素通常被视为第一个顺序管理细分,但在某些情况下,它还包含国家/地区、依赖项或区域中的第二、第三或第四个顺序细分。 |
|
countryRegion | ||
formattedAddress |
string |
带格式的地址属性 |
intersection |
结果的地址。 |
|
locality |
string |
locality 属性 |
neighborhood |
string |
邻里属性 |
postalCode |
string |
邮政编码属性 |
AdminDistricts
地址所在国家或地区的细分名称。 此元素通常被视为第一个顺序管理细分,但在某些情况下,它还包含国家/地区、依赖项或区域中的第二、第三或第四个顺序细分。
名称 | 类型 | 说明 |
---|---|---|
name |
string |
相应 adminDistrict 字段的名称,对于 adminDistrict[0],可以是州的全名,例如 Washington,对于 adminDistrict[1],这可能是县的全名 |
shortName |
string |
对应 adminDistrict 字段的短名称,对于 adminDistrict[0],可以是州的短名称,例如 WA,对于 adminDistrict[1],这可能是县的短名称 |
CalculationMethodEnum
用于计算地理编码点的方法。
名称 | 类型 | 说明 |
---|---|---|
Interpolation |
string |
地理编码点已使用内插与道路上的点匹配。 |
InterpolationOffset |
string |
地理编码点与道路上的点匹配,使用内插和额外的偏移量将点移动到街道的一侧。 |
Parcel |
string |
地理编码点与地块的中心匹配。 |
Rooftop |
string |
地理编码点与建筑物的屋顶匹配。 |
ConfidenceEnum
地理编码位置结果为匹配的置信度级别。 将此值与匹配代码一起使用,以确定有关匹配的更完整信息。
地理编码位置的置信度基于许多因素,包括地理编码位置和用户位置的相对重要性(如果指定)。
名称 | 类型 | 说明 |
---|---|---|
High |
string |
如果置信度设置为 如果请求包含位置或视图,则排名可能会相应地更改。 例如,对“Paris”的位置查询将置信返回“法国巴黎”和“Paris, TX”。 |
Low |
string |
|
Medium |
string |
在某些情况下,返回的匹配项可能与请求中提供的信息不同。 例如,请求可以指定地址信息,而地理编码服务可能只能匹配邮政编码。 在这种情况下,如果地理编码服务确信邮政编码与数据匹配,则置信度设置为 如果查询中的位置信息不明确,并且没有其他信息对位置 (进行排名,例如用户位置或位置) 的相对重要性,则置信度设置为 如果查询中的位置信息未提供对特定位置进行地理编码的足够信息,可能会返回不太精确的位置值,并且置信度设置为 |
CountryRegion
名称 | 类型 | 说明 |
---|---|---|
ISO |
string |
国家/地区的 ISO |
name |
string |
国家/地区的名称 |
ErrorAdditionalInfo
资源管理错误附加信息。
名称 | 类型 | 说明 |
---|---|---|
info |
object |
其他信息。 |
type |
string |
其他信息类型。 |
ErrorDetail
错误详细信息。
名称 | 类型 | 说明 |
---|---|---|
additionalInfo |
错误附加信息。 |
|
code |
string |
错误代码。 |
details |
错误详细信息。 |
|
message |
string |
错误消息。 |
target |
string |
错误目标。 |
ErrorResponse
错误响应
名称 | 类型 | 说明 |
---|---|---|
error |
错误对象。 |
FeatureCollectionEnum
FeatureCollection 对象的类型必须为 FeatureCollection。
名称 | 类型 | 说明 |
---|---|---|
FeatureCollection |
string |
FeaturesItem
名称 | 类型 | 说明 |
---|---|---|
bbox |
number[] |
边界框。 使用的投影 - EPSG:3857。 有关详细信息,请参阅 RFC 7946 。 |
geometry |
有效的 |
|
id |
string |
返回的功能的 ID |
properties | ||
type |
功能的类型必须为“功能”。 |
FeatureTypeEnum
功能的类型必须为“功能”。
名称 | 类型 | 说明 |
---|---|---|
Feature |
string |
GeocodePoints
地理编码点的集合,它们在计算方式及其建议用途方面有所不同。
名称 | 类型 | 说明 |
---|---|---|
calculationMethod |
用于计算地理编码点的方法。 |
|
geometry |
有效的 |
|
usageTypes |
地理编码点的最佳用途。
每个地理编码点都定义为一个 |
GeocodingBatchRequestBody
要处理的地址地理编码查询/请求的列表。 该列表最多可以包含 100 个查询,并且必须至少包含 1 个查询。
名称 | 类型 | 说明 |
---|---|---|
batchItems |
要处理的查询列表。 |
GeocodingBatchRequestItem
Batch Query 对象
名称 | 类型 | 默认值 | 说明 |
---|---|---|---|
addressLine |
string |
与区域相关的地址的官方街道线,由位置或邮政代码属性指定。 此元素的典型用途是提供街道地址或任何官方地址。 如果提供了查询,则不应使用此参数。 |
|
adminDistrict |
string |
地址的国家/地区细分部分,例如 WA。 如果提供了查询,则不应使用此参数。 |
|
adminDistrict2 |
string |
结构化地址的县,例如 King。 如果提供了查询,则不应使用此参数。 |
|
adminDistrict3 |
string |
结构化地址的命名区域。 如果提供了查询,则不应使用此参数。 |
|
bbox |
number[] |
地球上定义为边界框对象的矩形区域。 矩形的边由经度和纬度值定义。 有关详细信息,请参阅位置和区域类型。 指定此参数时,计算位置查询结果时会考虑地理区域。 示例:[lon1,lat1,lon2,lat2] |
|
coordinates |
number[] |
地球上指定为经度和纬度的点。 指定此参数时,会考虑用户的位置,返回的结果可能与用户更相关。 示例:[lon, lat] |
|
countryRegion |
string |
地理编码结果的信号到指定的 ISO 3166-1 Alpha-2 区域/国家/地区代码 ,例如 FR./ 如果提供了查询,则不应使用此参数。 |
|
locality |
string |
地址的“位置”部分,例如“西雅图”。 如果提供了查询,则不应使用此参数。 |
|
optionalId |
string |
将在相应的 batchItem 中显示的请求的 ID |
|
postalCode |
string |
地址的邮政编码部分。 如果提供了查询,则不应使用此参数。 |
|
query |
string |
一个字符串,包含有关位置的信息,例如地址或地标名称。 |
|
top |
integer |
5 |
将返回的最大响应数。 默认值:5,最小值:1,最大值:20。 |
view |
string |
auto |
一个指定 ISO 3166-1 Alpha-2 区域/国家/地区代码的字符串。 这将更改地缘政治争议边界和标签,使其与指定的用户区域保持一致。 |
GeocodingBatchResponse
此对象是从成功的地理编码 Batch 服务调用返回的。
名称 | 类型 | 说明 |
---|---|---|
batchItems |
包含批处理结果的数组。 |
|
nextLink |
string |
是指向返回的功能的下一页的链接。 如果是最后一页,则不使用此字段。 |
summary |
批处理请求摘要 |
GeocodingBatchResponseItem
名称 | 类型 | 说明 |
---|---|---|
error |
错误详细信息。 |
|
features | ||
nextLink |
string |
是指向返回的功能的下一页的链接。 如果是最后一页,则不使用此字段。 |
optionalId |
string |
batchItem 的 id,该 ID 与请求中的 ID 相同 |
type |
FeatureCollection 对象的类型必须为 FeatureCollection。 |
GeoJsonPoint
有效的 GeoJSON Point
几何类型。 有关详细信息,请参阅 RFC 7946 。
名称 | 类型 | 说明 |
---|---|---|
bbox |
number[] |
边界框。 使用的投影 - EPSG:3857。 有关详细信息,请参阅 RFC 7946 。 |
coordinates |
number[] |
是 |
type |
string:
Point |
指定 |
Intersection
结果的地址。
名称 | 类型 | 说明 |
---|---|---|
baseStreet |
string |
位置的主要街道。 |
displayName |
string |
交集的完整名称。 |
intersectionType |
string |
交集的类型。 |
secondaryStreet1 |
string |
第一条相交的街道。 |
secondaryStreet2 |
string |
如果有,则为第二条交叉街道。 |
MatchCodesEnum
一个或多个表示响应中每个位置的地理编码级别的匹配代码值。
例如,匹配代码为 和 Ambiguous
的Good
地理编码位置意味着已找到多个地理编码位置来获取位置信息,并且地理编码服务没有向上搜索来查找匹配项。
同样,匹配代码为 和 UpHierarchy
的Ambiguous
地理编码位置意味着找不到与所提供的所有位置信息匹配的地理编码位置,因此地理编码服务必须向上搜索层次结构并在该级别找到多个匹配项。 up 和 UpHierarchy
结果的一个Ambiguous
示例是,当你提供完整的地址信息,但地理编码服务找不到街道地址的匹配项,而是返回多个 RoadBlock 值的信息。
可能的值为:
Good
:该位置只有一个匹配项,或者所有返回的匹配项都被视为强匹配项。 例如,纽约的查询返回多个 Good 匹配项。
Ambiguous
:位置是一组可能的匹配项之一。 例如,当您查询街道地址 128 Main St.时,响应可能会返回 128 北主街和 128 南主街的两个位置,因为没有足够的信息来确定要选择的选项。
UpHierarchy
:位置表示地理层次结构的上移。 当未找到与位置请求匹配项时,将返回不太精确的结果时,就会发生这种情况。 例如,如果找不到所请求地址的匹配项,则可能会返回具有 RoadBlock 实体类型的 匹配代码 UpHierarchy
。
名称 | 类型 | 说明 |
---|---|---|
Ambiguous |
string |
|
Good |
string |
|
UpHierarchy |
string |
Properties
名称 | 类型 | 说明 |
---|---|---|
address |
结果的地址 |
|
confidence |
地理编码位置结果为匹配的置信度级别。 将此值与匹配代码一起使用,以确定有关匹配的更完整信息。 地理编码位置的置信度基于许多因素,包括地理编码位置和用户位置的相对重要性(如果指定)。 |
|
geocodePoints |
地理编码点的集合,它们在计算方式及其建议用途方面有所不同。 |
|
matchCodes |
一个或多个表示响应中每个位置的地理编码级别的匹配代码值。 例如,匹配代码为 和 同样,匹配代码为 和 可能的值为:
|
|
type |
string |
下列其中一项:
|
Summary
批处理请求摘要
名称 | 类型 | 说明 |
---|---|---|
successfulRequests |
integer |
批处理中成功的请求数 |
totalRequests |
integer |
批处理中的请求总数 |
UsageTypeEnum
地理编码点的最佳用途。
每个地理编码点都定义为一个 Route
点和/或一个 Display
点。
如果要创建指向该位置的路由,请使用 Route
点。 如果要在地图上显示位置,请使用 Display
点。 例如,如果位置是公园,则 Route
点可以指定公园的入口,你可以用汽车进入,而 Display
点可能是指定公园中心的点。
名称 | 类型 | 说明 |
---|---|---|
Display |
string |
|
Route |
string |