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 http POST que envia lotes de até 100 consultas para API de geocodificação reversa usando uma única solicitação.

Enviar solicitação de lote síncrona

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

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

Corpo POST para solicitação em lote

Para enviar o consultas de de geocodificação reversa, você usará uma solicitação POST em que o corpo da solicitação conterá a matriz de batchItems no formato json e o cabeçalho Content-Type será definido como application/json. Aqui está um corpo de solicitação de exemplo que contém 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 URI de de geocodificação reversacompatíveis.

O lote deve conter pelo menos 1 consulta.

Modelo de resposta em lote

A resposta em lote contém um componente summary que indica o totalRequests que faziam parte da solicitação em lote original e successfulRequests consultas que foram executadas com êxito. A resposta em lote também inclui uma matriz de 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 em lote. Cada item é de um dos seguintes tipos:

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

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

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

Parâmetros de URI

Cabeçalho da solicitação

Corpo da solicitação

Respostas

Segurança

AADToken

Estas são as Fluxos de do Microsoft Entra OAuth 2.0. Quando emparelhado com acesso baseado em função do Azure controle, ele pode ser usado para controlar o acesso às APIs REST do Azure Mapas. Os controles de acesso baseados em função do Azure são usados para designar o acesso a uma ou mais sub-recursos ou conta de recurso do Azure Mapas. 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 Mapas.

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

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

Escopos

subscription-key

Essa é uma chave compartilhada provisionada ao criar um recurso do Azure Mapas por meio do plano de gerenciamento do Azure por meio do portal do Azure, do PowerShell, da CLI, dos SDKs do Azure ou das APIs REST.

Com essa chave, qualquer aplicativo está autorizado a acessar todas as APIs REST. Em outras palavras, elas podem atualmente ser tratadas como chaves mestras para a conta para a qual são emitidas.

Para aplicativos expostos publicamente, nossa recomendação é usar o acesso de servidor a servidor de APIs REST do Azure Mapas, em que essa chave pode ser armazenada com segurança.

Tipo: apiKey
Em: header

SAS Token

Esse é um token de assinatura de acesso compartilhado criado a partir da operação LISTA SAS no recurso do Azure Mapas por meio do plano de gerenciamento do Azure por meio do portal do Azure, do PowerShell, da CLI, dos SDKs do Azure ou das APIs REST.

Com esse token, qualquer aplicativo está autorizado a acessar com controles de acesso baseados em função do Azure e controle refinado para expiração, taxa e região(s) 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 protegida 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 de mapa de 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=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"
    }
  ]
}

Definições

Address

O endereço do resultado

AdminDistricts

O nome da subdivisão no país ou região para um endereço. Esse elemento normalmente é tratado como a subdivisão administrativa de primeira ordem, mas em alguns casos também contém a subdivisão de segunda, terceira ou quarta ordem em um país, dependência ou região.

CalculationMethodEnum

O método que foi usado para calcular o ponto de código geográfico.

ConfidenceEnum

O nível de confiança de que o resultado do local geocodificado é uma correspondência. Use esse valor com o código de correspondência para determinar informações mais completas sobre a correspondência.

A confiança de um local geocodificado baseia-se em muitos fatores, incluindo a importância relativa do local geocodificado e a localização do usuário, se especificado.

CountryRegion

ErrorAdditionalInfo

As informações adicionais do erro de gerenciamento de recursos.

ErrorDetail

O detalhe do erro.

ErrorResponse

Resposta de erro

FeatureCollectionEnum

O tipo de objeto FeatureCollection deve ser FeatureCollection.

FeaturesItem

FeatureTypeEnum

O tipo de um recurso deve ser Feature.

GeocodePoints

Uma coleção de pontos de código geográfico que diferem em como eles foram calculados e seu uso sugerido.

GeocodingBatchResponse

Esse objeto é retornado de uma chamada de serviço do Lote de Geocodificação bem-sucedida.

GeocodingBatchResponseItem

GeoJsonPoint

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

Intersection

O endereço do resultado.

MatchCodesEnum

Um ou mais valores de código correspondentes que representam o nível de geocodificação para cada local na resposta.

Por exemplo, um local geocodificado com códigos de correspondência de Good e Ambiguous significa que mais de um local de código geográfico foi encontrado para as informações de localização e que o serviço de geocódigo não tinha uma hierarquia de pesquisa para encontrar uma correspondência.

Da mesma forma, um local geocodificado com códigos de correspondência de Ambiguous e UpHierarchy implica que não foi possível encontrar um local de código geográfico que correspondesse a todas as informações de localização fornecidas, de modo que o serviço de geocódigo teve que pesquisar a hierarquia superior e encontrou várias correspondências nesse nível. Um exemplo de um resultado Ambiguous e UpHierarchy é quando você fornece informações de endereço completas, mas o serviço de geocodificação não pode localizar uma correspondência para o endereço de rua e, em vez disso, retorna informações para mais de um valor roadblock.

Os valores possíveis são:

Good: o local tem apenas uma correspondência ou todas as correspondências retornadas são consideradas correspondências fortes. Por exemplo, uma consulta para Nova York retorna várias correspondências boas.

Ambiguous: o local é uma de um conjunto de possíveis correspondências. Por exemplo, quando você consulta o endereço da rua 128 Main St., a resposta pode retornar dois locais para 128 North Main St. e 128 South Main St. porque não há informações suficientes para determinar qual opção escolher.

UpHierarchy: o local representa um movimento para cima da hierarquia geográfica. Isso ocorre quando uma correspondência para a solicitação de local não foi encontrada, portanto, um resultado menos preciso é retornado. Por exemplo, se uma correspondência para o endereço solicitado não puder ser encontrada, um código de correspondência de UpHierarchy com um tipo de entidade RoadBlock poderá ser retornado.

Properties

ResultTypeEnum

Especifique os tipos de entidade desejados na resposta. Somente os tipos especificados serão retornados. Se o ponto não puder ser mapeado para os tipos de entidade especificados, nenhuma informação de local será retornada na resposta. O valor padrão é todas as entidades possíveis. Uma lista separada por vírgulas de tipos de entidade selecionada nas opções a seguir.

• Endereço
• Vizinhança
• PopulatedPlace
• Postcode1
• AdminDivision1
• AdminDivision2
• Região/País

Esses tipos de entidade são ordenados da entidade mais específica para a entidade menos específica. Quando entidades de mais de um tipo de entidade são encontradas, somente a entidade mais específica é retornada. Por exemplo, se você especificar Address e AdminDistrict1 como tipos de entidade e entidades foram encontrados para ambos os tipos, somente as informações da entidade Address serão retornadas na resposta.

ReverseGeocodingBatchRequestBody

A lista de consultas/solicitações de geocodificação reversa a serem processadas. A lista pode conter no máximo 100 consultas e deve conter pelo menos 1 consulta.

ReverseGeocodingBatchRequestItem

Objeto De Consulta em Lote

Summary

Resumo da solicitação em lote

UsageTypeEnum

O melhor uso para o ponto de código geográfico. Cada ponto de código geográfico é definido como um ponto de Route, um ponto Display ou ambos. Use Route pontos se estiver criando uma rota para o local. Use Display pontos se estiver mostrando o local em um mapa. Por exemplo, se o local for um parque, um ponto Route poderá especificar uma entrada para o parque em que você pode entrar com um carro e um ponto Display pode ser um ponto que especifica o centro do parque.