Search - Get Reverse Geocoding Batch

Use para enviar um lote de consultas para a API de Geocodificação Reversa em uma única solicitação.
A API Get Reverse Geocoding Batch é uma solicitação de POST HTTP que envia lotes de até 100 consultas para Geocodificação Reversa API usando uma única solicitação.

Enviar solicitação de lote síncrona

A API síncrona é recomendada para solicitações em lote leves. Quando o serviço recebe uma solicitação, ele responderá assim que os itens do lote forem calculados e não haverá possibilidade de recuperar os resultados posteriormente. A API síncrona retornará um erro de tempo limite (uma resposta 408) se a solicitação demorar mais de 60 segundos. O número de itens de lote é limitado a 100 para esta API.

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

Corpo POST para solicitação de lote

Para enviar as consultas de de geocodificação reversa , você usará uma solicitação de onde o corpo da solicitação conterá a matriz em formato e o cabeçalho será definido como . Aqui está um corpo de solicitação de exemplo contendo 2 consultas de de geocodificação reversa:

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

Uma geocodificação reversa objeto batchItem pode aceitar qualquer um dos parâmetros de URIgeocodificação reversa suportados.

O lote deve conter pelo menos 1 consulta.

Modelo de resposta em lote

A resposta em lote contém um componente summary que indica os totalRequests que faziam parte da solicitação de lote original e successfulRequests ou seja, consultas que foram executadas com êxito. A resposta em lote também inclui uma matriz batchItems que contém uma resposta para cada consulta na solicitação em lote. O batchItems conterá os resultados exatamente na mesma ordem em que as consultas originais foram enviadas na solicitação de lote. Cada item é de um dos seguintes tipos:

• GeocodingResponse - Se a consulta foi concluída com êxito.

• Error - Se a consulta falhou. Neste caso, a resposta conterá um code e um message.

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

Parâmetros do URI

Cabeçalho do Pedido

Corpo do Pedido

Respostas

Segurança

AadToken

Estes são os fluxos Microsoft Entra OAuth 2.0. Quando combinado com controlo Azure baseado em funções, pode ser usado para controlar o acesso a APIs REST Azure Maps. Os controlos de acesso baseados em papéis do Azure são usados para designar o acesso a uma ou mais contas ou subrecursos de recursos do Azure Maps. Qualquer usuário, grupo ou entidade de serviço pode receber acesso por meio de uma função interna ou uma função personalizada composta por uma ou mais permissões para APIs REST do Azure Maps.

Para implementar cenários, recomendamos a visualização conceitos de autenticação. Em resumo, essa definição de segurança fornece uma solução para modelar aplicativos(s) por meio de objetos capazes de controle de acesso em APIs e escopos específicos.

Tipo: oauth2
Fluxo: implicit
URL de Autorização: https://login.microsoftonline.com/common/oauth2/authorize

Âmbitos

subscription-key

Esta é uma chave compartilhada que é provisionada quando você Criar uma conta do Azure Maps no portal do Azure ou usando PowerShell, CLI, SDKs do Azure ou API REST.

Com essa chave, qualquer aplicativo pode acessar todas as APIs REST. Em outras palavras, essa chave pode ser usada como uma chave mestra na conta em que eles são emitidos.

Para aplicativos expostos publicamente, nossa recomendação é usar a abordagem de de aplicativos cliente confidenciais para acessar APIs REST do Azure Maps para que sua chave possa ser armazenada com segurança.

Tipo: apiKey
Em: header

SAS Token

Este é um token de assinatura de acesso compartilhado criado a partir da operação Listar SAS no de recursos do Azure Maps por meio do plano de gerenciamento do Azure por meio do portal do Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.

Com esse token, qualquer aplicativo é autorizado a acessar com controles de acesso baseados em função do Azure e controle de grão fino para a expiração, taxa e região(ões) de uso para o token específico. Em outras palavras, o Token SAS pode ser usado para permitir que os aplicativos controlem o acesso de forma mais segura do que a chave compartilhada.

Para aplicativos expostos publicamente, nossa recomendação é configurar uma lista específica de origens permitidas no de recursos da conta do Map para limitar o abuso de renderização e renovar regularmente o Token SAS.

Tipo: apiKey
Em: header

Exemplos

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"
    }
  ]
}

Definições

Address

O endereço de uma localização geocodificada ou sugerida por autocompletamento, analisada em campos estruturados. A escassez é normal: apenas os campos que a entidade resolvida fornece são povoados. Por exemplo, streetName e streetNumber aparece apenas para endereços ao nível da rua, e intersection aparece apenas para resultados de interseções rodoviárias.

AddressAdminDistrictsItem

Uma subdivisão administrativa que contém um endereço. Por exemplo, um estado, província ou condado. Devolvido como uma entrada no array principal Address.adminDistricts , onde as entradas são ordenadas do mais grosseiro para o mais fino.

AddressCountryRegion

O país ou região que contém o endereço, identificado pelo seu nome de exibição e pelo código de país ISO 3166-1 Alpha-2. Qualquer um dos campos pode ser omitido numa dada resposta.

Azure.Core.Foundations.Error

O objeto de erro.

Azure.Core.Foundations.ErrorResponse

Uma resposta contendo detalhes do erro.

Azure.Core.Foundations.InnerError

Um objeto que contém informações mais específicas sobre o erro. De acordo com Azure diretrizes da API REST - https://aka.ms/AzureRestApiGuidelines#handling-errors.

CalculationMethodEnum

O método que foi usado para calcular o ponto de geocódigo.

ConfidenceEnum

O nível de confiança de que o resultado da localização geocodificada é uma correspondência. Use este valor juntamente com os códigos de correspondência para obter informações mais completas sobre o jogo.

A confiança de uma localização geocodificada baseia-se em muitos fatores, incluindo a importância relativa da localização geocodificada e a localização do utilizador, se especificada.

ErrorAdditionalInfo

O erro de gerenciamento de recursos informações adicionais.

ErrorDetail

O detalhe do erro.

FeatureCollectionEnum

O GeoJSON tipo de objeto utilizado na raiz das respostas bem-sucedidas das operações de geocodificação direta, geocodificação reversa e autocompletar (incluindo as suas variantes em lote). O único valor é FeatureCollection, conforme definido no RFC 7946. Get Polygon é a única exceção: a sua raiz de resposta é um GeoJSON Feature, veja FeatureTypeEnum.

FeaturesItem

Uma única entrada no features array de um GeocodingResponse, conforme a forma do GeoJSON Feature objeto. Representa uma localização geocodificada: dados estruturados em properties, uma coordenada representativa em geometry, e uma caixa delimitadora opcional em bbox.

FeaturesItemProperties

A properties carga útil de uma funcionalidade num GeocodingResponse. Transporta os indicadores de tipo de entidade e de qualidade de correspondência para a localização geocodificada, os seus componentes de endereço analisados e um ou mais pontos de geocódigo que associam a localização a coordenadas específicas.

FeatureTypeEnum

O GeoJSON tipo de objeto para Feature os objetos. Etiqueta cada entrada dentro do features array de uma FeatureCollection resposta (geocodificação, geocodificação reversa, autocompletamento) e aparece na raiz da Get Polygon resposta. O único valor é Feature, conforme definido no RFC 7946.

GeocodePointsItem

Um ponto de geocódigo para uma localização: uma coordenada mais metadados que descrevem como o ponto foi calculado (calculationMethod) e para que é mais adequado (usageTypes). Uma única funcionalidade normalmente retorna separadas Display e Route aponta para que os chamadores possam escolher a que se adequa à tarefa.

GeocodingBatchResponse

O corpo de resposta bem-sucedida retornou por Get Geocoding Batch. Transporta um summary número de consultas submetidas bem-sucedidas, mais um batchItems array contendo uma entrada de resposta por consulta no pedido, na mesma ordem do array do pedido batchItems .

GeocodingBatchResponseItem

Uma única entrada dentro GeocodingBatchResponse.batchItemsde , contendo o resultado de uma das consultas da entrada correspondente GeocodingBatchRequestBody.batchItems . Consultas bem-sucedidas surgem aqui geocodificadas features na mesma forma que GeocodingResponse; consultas falhadas apresentam informação de diagnóstico via error instead. Exatamente um de features ou error está preenchido por entrada.

GeocodingBatchResponseSummary

Transporta contagens agregadas para uma Get Geocoding Batch resposta: o tamanho do lote submetido e quantas das suas consultas foram processadas com sucesso. Usado como o tipo de GeocodingBatchResponse.summary.

GeoJsonObjectType

Especifica o tipo de GeoJSON. Deve ser um dos nove tipos de objeto GeoJSON válidos - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature e FeatureCollection.

GeoJsonPoint

Um tipo de geometria GeoJSON Point válido. Consulte RFC 7946 para obter detalhes.

Intersection

Detalhes de interseção para um endereço resolvidos como um cruzamento rodoviário — a esquina onde duas ou mais ruas nomeadas se encontram. Preenchido apenas quando a entidade resolvida é um RoadIntersection; o pai Address.intersection é de outra forma omitido.

MatchCodesEnum

Um valor de código de correspondência que indica como o serviço de geocodificação produziu um determinado resultado de localização. O matchCodes campo numa característica é um array destes valores; combine-os com confidence e type para avaliar a qualidade da correspondência.

ResultTypeEnum

Um tipo de entidade devolvido pela Get Reverse Geocoding Batch operação. Fornecido como um ou mais valores no campo por lote resultTypes para restringir a resposta desse item a tipos específicos de localizações; quando o campo é omitido, todos os tipos de entidade são elegíveis. Quando entidades de mais do que um tipo correspondem a uma coordenada, apenas a mais específica é retornada. Listados do mais específico ao menos específico: Address, Neighborhood, PopulatedPlacePostcode1, AdminDivision1, , AdminDivision2, , . CountryRegion

ReverseGeocodingBatchRequestBody

O órgão solicitante para a Get Reverse Geocoding Batch operação. Transporta uma ou mais consultas individuais de geocodificação inversa — entre 1 e 100, incluindo — que o serviço processa como uma única chamada e devolve como um array paralelo batchItems em GeocodingBatchResponse.

ReverseGeocodingBatchRequestItem

Uma consulta de geocodificação reversa dentro de um ReverseGeocodingBatchRequestBody.batchItems array. Cada item é um pedido independente de geocodificação inversa equivalente a uma única chamada para Get Reverse Geocoding, expressa como campos em vez de parâmetros de consulta URL. Especifique a localização a geocodificar inversamente via coordinates; opcionalmente restringir os tipos de entidade via resultTypes e a visão geopolítica via view.

UsageTypeEnum

O uso pretendido para um ponto de geocódigo. Um ponto de geocódigo devolvido pelo serviço transporta um ou mais tipos de utilização que indicam como uma aplicação cliente deve consumir o ponto: por exemplo, mostrar a localização num mapa versus encaminhar um veículo para ele.