Search - Get Reverse Geocoding Batch

Se usa para enviar un lote de consultas a la API de geocodificación inversa en una sola solicitud.
La API de Get Reverse Geocoding Batch es una solicitud de POST HTTP que envía lotes de hasta 100 consultas a API de geocodificación inversa mediante una sola solicitud.

Enviar solicitud por lotes sincrónica

Se recomienda la API sincrónica para solicitudes por lotes ligeras. Cuando el servicio recibe una solicitud, responderá tan pronto como se calculen los elementos por lotes y no habrá posibilidad de recuperar los resultados más adelante. La API sincrónica devolverá un error de tiempo de espera (una respuesta 408) si la solicitud tarda más de 60 segundos. El número de elementos por lotes se limita a 100 para esta API.

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version={api-version}

Cuerpo POST para solicitud por lotes

Para enviar las consultas de de geocodificación inversa , usará una solicitud de donde el cuerpo de la solicitud contendrá la matriz de en formato y el encabezado se establecerá en . Este es un cuerpo de solicitud de ejemplo que contiene 2 geocodificación inversa consultas:

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

Un objeto geocodificación inversa batchItem puede aceptar cualquiera de los parámetros de geocodificación inversa admitidos URI.

El lote debe contener al menos 1 consulta de.

Modelo de respuesta por lotes

La respuesta por lotes contiene un componente de summary que indica el totalRequests que formaron parte de la solicitud por lotes original y successfulRequests es decir, las consultas que se ejecutaron correctamente. La respuesta por lotes también incluye una matriz de batchItems que contiene una respuesta para cada consulta y cada consulta de la solicitud por lotes. El batchItems contendrá los resultados en el mismo orden en que se enviaron las consultas originales en la solicitud por lotes. Cada elemento es de uno de los siguientes tipos:

• GeocodingResponse: si la consulta se completó correctamente.

• Error: si se produjo un error en la consulta. La respuesta contendrá un code y un message en este caso.

POST {endpoint}/reverseGeocode:batch?api-version=2026-01-01

Parámetros de identificador URI

Encabezado de la solicitud

Cuerpo de la solicitud

Respuestas

Seguridad

AadToken

Estos son los flujos Microsoft Entra OAuth 2.0. Cuando se combina con el control de acceso basado en roles Azure puede usarse para controlar el acceso a Azure Maps APIs REST. Los controles de acceso basados en roles de Azure se utilizan para designar el acceso a una o más cuentas o subrecursos de recursos de Azure Maps. Se puede conceder acceso a cualquier usuario, grupo o entidad de servicio a través de un rol integrado o de un rol personalizado compuesto por uno o varios permisos para las API REST de Azure Maps.

Para implementar escenarios, se recomienda ver conceptos de autenticación. En resumen, esta definición de seguridad proporciona una solución para modelar aplicaciones a través de objetos capaces de controlar el acceso en determinadas API y ámbitos.

Tipo: oauth2
Flujo: implicit
Dirección URL de autorización: https://login.microsoftonline.com/common/oauth2/authorize

Ámbitos

subscription-key

Se trata de una clave compartida que se aprovisiona al Creación de una cuenta de Azure Maps en Azure Portal o mediante PowerShell, la CLI, los SDK de Azure o la API REST.

Con esta clave, cualquier aplicación puede acceder a todas las API REST. En otras palabras, esta clave se puede usar como clave maestra en la cuenta en la que se emiten.

Para las aplicaciones expuestas públicamente, nuestra recomendación es usar las aplicaciones cliente confidenciales enfoque acceder a las API REST de Azure Maps para que la clave se pueda almacenar de forma segura.

Tipo: apiKey
En: header

SAS Token

Se crea un token de firma de acceso compartido a partir de la operación List SAS en el recurso de Azure Maps a través del plano de administración de Azure a través de Azure Portal, PowerShell, CLI, SDK de Azure o API REST.

Con este token, cualquier aplicación tiene autorización para acceder a los controles de acceso basados en rol de Azure y el control específico a la expiración, la tasa y las regiones de uso para el token determinado. Es decir, el token de SAS se puede usar para permitir que las aplicaciones controle el acceso de forma más segura que la clave compartida.

En el caso de las aplicaciones expuestas públicamente, nuestra recomendación es configurar una lista específica de orígenes permitidos en el recurso de cuenta de mapa de limitar el abuso de representación y renovar periódicamente el token de SAS.

Tipo: apiKey
En: header

Ejemplos

A Reverse Geocoding Batch API call containing 2 Reverse Geocoding queries

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2026-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"
    }
  ]
}

Definiciones

Address

La dirección de una ubicación sugerida por geocodificación o autocompletado, analizada en campos estructurados. La escasez es normal: solo se llenan los campos que suministra la entidad resuelta. Por ejemplo, streetName y streetNumber aparecen solo para direcciones a nivel de calle, y intersection aparecen solo para resultados de intersecciones de carretera.

AddressAdminDistrictsItem

Una subdivisión administrativa que contiene una dirección. Por ejemplo, un estado, provincia o condado. Se devuelve como una entrada en el array principal Address.adminDistricts , donde las entradas se ordenan de más grueso a fino.

AddressCountryRegion

El país o región que contiene la dirección, identificado por su nombre de visualización y el código de país ISO 3166-1 Alpha-2. Cualquiera de los dos campos puede omitirse en una respuesta dada.

Azure.Core.Foundations.Error

Objeto de error.

Azure.Core.Foundations.ErrorResponse

Respuesta que contiene los detalles del error.

Azure.Core.Foundations.InnerError

Objeto que contiene información más específica sobre el error. Según las directrices de Azure API REST - https://aka.ms/AzureRestApiGuidelines#handling-errors.

CalculationMethodEnum

Método que se usó para calcular el punto de código geográfico.

ConfidenceEnum

Nivel de confianza de que el resultado de la ubicación geocodificada es una coincidencia. Utiliza este valor junto con los códigos de coincidencia para obtener información más completa sobre la coincidencia.

La confianza de una ubicación geocodificada se basa en muchos factores, incluyendo la importancia relativa de la ubicación geocodificada y la ubicación del usuario, si se especifica.

ErrorAdditionalInfo

Información adicional sobre el error de administración de recursos.

ErrorDetail

Detalle del error.

FeatureCollectionEnum

El GeoJSON tipo de objeto utilizado en la raíz de las respuestas exitosas de las operaciones de geocodificación directa, geocodificación inversa y autocompletado (incluyendo sus variantes por lotes). El único valor es FeatureCollection, según se define en el RFC 7946. Get Polygon es la única excepción: su raíz de respuesta es un GeoJSON Feature, véase FeatureTypeEnum.

FeaturesItem

Una sola entrada en el features array de un GeocodingResponse, conforme a la forma del GeoJSON Feature objeto. Representa una ubicación geocodificada: datos estructurados en properties, una coordenada representativa en geometry, y una caja delimitadora opcional en bbox.

FeaturesItemProperties

La properties carga útil de una característica en un GeocodingResponse. Lleva los indicadores de tipo de entidad y calidad de coincidencia para la ubicación geocodificada, sus componentes de dirección analizada y uno o más puntos de geocodificación que vinculan la ubicación a coordenadas específicas.

FeatureTypeEnum

El GeoJSON tipo de objeto para Feature los objetos. Etiqueta cada entrada dentro del features array de una FeatureCollection respuesta (geocodificación, geocodificación inversa, autocompletado) y aparece en la raíz de la Get Polygon respuesta. El único valor es Feature, según se define en el RFC 7946.

GeocodePointsItem

Un punto de geocodificación para una ubicación: una coordenada más metadatos que describen cómo se calculó el punto (calculationMethod) y para qué es mejor adecuado (usageTypes). Una sola característica normalmente devuelve separadas Display y Route apuntan para que los llamantes puedan elegir la que se adapte a la tarea.

GeocodingBatchResponse

El cuerpo de respuesta exitosa devuelto por Get Geocoding Batch. Incluye cuántas summary consultas enviadas tuvieron éxito más un batchItems array que contiene una entrada de respuesta por consulta en la solicitud, en el mismo orden que el array de la solicitud batchItems .

GeocodingBatchResponseItem

Una sola entrada dentro GeocodingBatchResponse.batchItemsde , que lleva el resultado de una de las consultas de la entrada correspondiente GeocodingBatchRequestBody.batchItems . Las consultas exitosas aparecen geocodificadas features aquí en la misma forma que GeocodingResponse; consultas fallidas muestran información diagnóstica mediante error en su lugar. Exactamente uno de features o error está poblado por entrada.

GeocodingBatchResponseSummary

Contiene el recuento agregado para una Get Geocoding Batch respuesta: el tamaño del lote enviado y cuántas de sus consultas se han procesado correctamente. Usado como el tipo de GeocodingBatchResponse.summary.

GeoJsonObjectType

Especifica el tipo de GeoJSON. Debe ser uno de los nueve tipos de objeto GeoJSON válidos: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature y FeatureCollection.

GeoJsonPoint

Un tipo de geometría GeoJSON Point válido. Consulte RFC 7946 para obtener más información.

Intersection

Los detalles de la intersección de una dirección se resolvían como una intersección de carretera — la esquina donde se encuentran dos o más calles con nombre. Se puede repoblar solo cuando la entidad resuelta es un RoadIntersection; el padre Address.intersection se omite de otro modo.

MatchCodesEnum

Un valor de código de coincidencia que indica cómo el servicio de geocodificación produjo un resultado de ubicación concreta. El matchCodes campo de una característica es un array de estos valores; combínalos con confidence y type para evaluar la calidad de la coincidencia.

ResultTypeEnum

Un tipo de entidad devuelto por la Get Reverse Geocoding Batch operación. Se proporciona como uno o más valores en el campo por lote resultTypes para restringir la respuesta de ese elemento a tipos específicos de ubicaciones; cuando se omite el campo, todos los tipos de entidades son elegibles. Cuando las entidades de más de un tipo coinciden con una coordenada, solo se devuelve la más específica. Listados de más específico a menos específico: Address, Neighborhood, PopulatedPlacePostcode1, AdminDivision1, , AdminDivision2, , . CountryRegion

ReverseGeocodingBatchRequestBody

El organismo solicitante de la Get Reverse Geocoding Batch operación. Transporta una o más consultas individuales de geocodificación inversa — entre 1 y 100, incluyendo — que el servicio procesa como una sola llamada y devuelve como un array paralelo batchItems en GeocodingBatchResponse.

ReverseGeocodingBatchRequestItem

Una consulta de geocodificación inversa dentro de un ReverseGeocodingBatchRequestBody.batchItems array. Cada elemento es una solicitud independiente de geocodificación inversa equivalente a una sola llamada a Get Reverse Geocoding, expresada como campos en lugar de como parámetros de consulta URL. Especificar la ubicación a geocodificar inversamente mediante coordinates; opcionalmente restringir los tipos de entidades mediante resultTypes y la vista geopolítica mediante view.

UsageTypeEnum

El uso previsto para un punto de geocódigo. Un punto de geocodificación devuelto por el servicio lleva uno o más tipos de uso que indican cómo una aplicación cliente debe consumir el punto: por ejemplo, mostrar la ubicación en un mapa frente a enrutar un vehículo hacia él.