Search - Get Reverse Geocoding Batch

用于在单个请求中向 反向地理编码 API 发送一批查询。

API 是一个 HTTP 请求，它使用单个请求向反向地理编码 API 发送多达 100 个 100 个 查询的批处理。

提交同步批处理请求

建议对轻型批处理请求使用同步 API。 当服务收到请求时，它会在计算批处理项后立即做出响应，并且以后将无法检索结果。 如果请求花费的时间超过 60 秒，同步 API 将返回超时错误（408 响应）。 批项数限制为此 API 100 个。

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01

批处理请求的 POST 正文

若要发送 反向地理编码 查询，将使用 POST 请求，其中请求正文将包含 batchItems 格式的 json 数组，Content-Type 标头将设置为 application/json。 下面是一个示例请求正文，其中包含 2 个 反向地理编码 查询：

{
  "batchItems": [
    {
      "coordinates": [-122.128275, 47.639429],
      "resultTypes": ["Address", "PopulatedPlace"]
    },
    {
      "coordinates": [-122.341979399674, 47.6095253501216]
    }
  ]
}

反向地理编码 batchItem 对象可以接受任何受支持的 反向地理编码URI 参数。

批处理应至少包含 1 个 查询 。

批处理响应模型

批处理响应包含一个 summary 组件，该组件指示作为原始批处理请求的一部分的 totalRequests，successfulRequests 即已成功执行的查询。 批处理响应还包括一个 batchItems 数组，其中包含批处理请求中每个查询的响应。 batchItems 将包含结果，其顺序与在批处理请求中发送原始查询的顺序完全相同。 每个项都是以下类型之一：

• GeocodingResponse - 如果查询成功完成。

• Error - 如果查询失败。 在这种情况下，响应将包含 code 和 message。

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2025-01-01

URI 参数

请求头

请求正文

响应

安全性

AADToken

这些 Microsoft Entra OAuth 2.0 流。 与 Azure 基于角色的访问配对时， 控制它可用于控制对 Azure Maps REST API 的访问。 Azure 基于角色的访问控制用于指定对一个或多个 Azure Maps 资源帐户或子资源的访问。 任何用户、组或服务主体都可以通过内置角色或由一个或多个对 Azure Maps REST API 的权限组成的自定义角色授予访问权限。

若要实现方案，建议查看 身份验证概念。 总之，此安全定义提供了一种解决方案，用于通过能够针对特定 API 和范围进行访问控制的对象对应用程序建模。

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

作用域

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 令牌可用于允许应用程序以比共享密钥更安全的方式控制访问。

对于公开的应用程序，建议在 映射帐户资源 上配置允许的源的特定列表，以限制呈现滥用并定期续订 SAS 令牌。

类型: apiKey
在: header

示例

A Reverse Geocoding Batch API call containing 2 Reverse Geocoding queries

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2025-01-01

{
  "batchItems": [
    {
      "coordinates": [
        -122.138681,
        47.630358
      ],
      "resultTypes": [
        "Address",
        "PopulatedPlace"
      ],
      "optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
    },
    {
      "coordinates": [
        47.630358,
        -122.138681
      ],
      "optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
    }
  ]
}

{
  "summary": {
    "successfulRequests": 1,
    "totalRequests": 2
  },
  "batchItems": [
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {
            "type": "Address",
            "confidence": "Medium",
            "matchCodes": [
              "Good"
            ],
            "address": {
              "locality": "Redmond",
              "adminDistricts": [
                {
                  "name": "Washington",
                  "shortName": "WA"
                },
                {
                  "name": "King County",
                  "shortName": "King Co."
                }
              ],
              "countryRegion": {
                "ISO": "US",
                "name": "United States"
              },
              "postalCode": "98052",
              "formattedAddress": "2267 152nd Ave NE, Redmond, Washington 98052, United States",
              "streetName": "152nd Ave NE",
              "streetNumber": "2267",
              "addressLine": "2267 152nd Ave NE"
            },
            "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
          ]
        }
      ],
      "optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
    },
    {
      "error": {
        "code": "Bad Request",
        "message": "The provided coordinates (-122.138681,47.630358) in coordinates field are invalid or out of range"
      },
      "optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
    }
  ]
}

定义

Address

结果的地址

AdminDistricts

地址所在国家或地区的细分名称。 此元素通常被视为第一个顺序管理细分，但在某些情况下，它还包含国家/地区、依赖项或区域的第二、第三或第四个顺序细分。

CalculationMethodEnum

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

ConfidenceEnum

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

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

CountryRegion

ErrorAdditionalInfo

资源管理错误附加信息。

ErrorDetail

错误详细信息。

ErrorResponse

错误响应

FeatureCollectionEnum

FeatureCollection 对象的类型必须是 FeatureCollection。

FeaturesItem

FeatureTypeEnum

特征的类型必须是功能。

GeocodePoints

一组地理编码点，这些点的计算方式及其建议的使用方式不同。

GeocodingBatchResponse

此对象是从成功的 Geocoding Batch 服务调用返回的。

GeocodingBatchResponseItem

GeoJsonPoint

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

Intersection

结果的地址。

MatchCodesEnum

一个或多个匹配代码值，表示响应中每个位置的地理编码级别。

例如，具有匹配代码的地理编码位置 Good 和 Ambiguous 意味着为位置信息找到了多个地理编码位置，并且地理编码服务没有搜索向上层次结构来查找匹配项。

同样，具有匹配代码的地理编码位置 Ambiguous 和 UpHierarchy 意味着找不到与提供的所有位置信息匹配的地理编码位置，因此地理编码服务必须搜索层次结构并在该级别找到多个匹配项。 Ambiguous 和 UpHierarchy 结果的一个示例是提供完整的地址信息，但地理编码服务找不到街道地址的匹配项，而是返回多个 RoadBlock 值的信息。

可能的值为：

Good：该位置只有一个匹配项或所有返回的匹配项被视为强匹配项。 例如，纽约的查询返回多个 Good 匹配项。

Ambiguous：位置是一组可能的匹配项之一。 例如，在查询街道地址 128 Main St.时，响应可能会返回 128 北主街和 128 南主街的两个位置，因为没有足够的信息来确定要选择的选项。

UpHierarchy：位置表示向上移动的地理层次结构。 如果未找到位置请求的匹配项，则会发生这种情况，因此会返回不太精确的结果。 例如，如果找不到所请求地址的匹配项，则可能会返回具有 RoadBlock 实体类型的 UpHierarchy 匹配代码。

Properties

ResultTypeEnum

指定响应中所需的实体类型。 仅返回指定的类型。 如果点无法映射到指定的实体类型，则响应中不会返回位置信息。 默认值是所有可能的实体。 从以下选项中选择的实体类型的逗号分隔列表。

• 地址
• 附近
• PopulatedPlace
• Postcode1
• AdminDivision1
• AdminDivision2
• CountryRegion

这些实体类型从最具体的实体排序到最不具体的实体。 当找到多个实体类型的实体时，仅返回最具体的实体。 例如，如果将 Address 和 AdminDistrict1 指定为两种类型的实体类型和实体，则响应中仅返回 Address 实体信息。

ReverseGeocodingBatchRequestBody

要处理的反向地理编码查询/请求的列表。 该列表最多可以包含 100 个查询，并且必须至少包含 1 个查询。

ReverseGeocodingBatchRequestItem

Batch Query 对象

Summary

批处理请求摘要

UsageTypeEnum

最适合地理编码点。 每个地理编码点都定义为 Route 点、Display 点或两者。 如果要创建指向位置的路由，请使用 Route 点。 如果在地图上显示位置，请使用 Display 点。 例如，如果位置是公园，Route 点可以指定公园的入口，可以使用汽车进入，而 Display 点可能是指定公园中心点。