Search - Get Geocoding Batch
Use para enviar um lote de consultas para a API Geocoding em uma única solicitação.
A Get Geocoding Batch API é uma solicitação HTTP POST que envia lotes de até 100 consultas para a API Geocoding em 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/geocode:batch?api-version={api-version}
Corpo POST para solicitação em lote
Para enviar as consultas de geocodificação , você usará uma POST solicitação em que o corpo da solicitação conterá a batchItems matriz no json formato e o Content-Type cabeçalho será definido como application/json. Aqui está um exemplo de corpo de solicitação contendo 2 consultas de geocodificação :
{
"batchItems": [
{
"addressLine": "One, Microsoft Way, Redmond, WA 98052",
"top": 2
},
{
"addressLine": "Pike Pl",
"adminDistrict": "WA",
"locality": "Seattle",
"top": 3
}
]
}
Um objeto batchItem de geocodificação pode aceitar qualquer um dos parâmetros de URI de geocodificação com suporte.
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á umcodee ummessagenesse caso.
POST {endpoint}/geocode:batch?api-version=2026-01-01
Parâmetros de URI
| Nome | Em | Obrigatório | Tipo | Description |
|---|---|---|---|---|
|
endpoint
|
path | True |
string |
|
|
api-version
|
query | True |
string minLength: 1 |
A versão da API a ser usada para esta operação. |
Cabeçalho da solicitação
| Nome | Obrigatório | Tipo | Description |
|---|---|---|---|
| x-ms-client-id |
string |
Especifica qual conta deve ser usada em conjunto com o modelo de segurança do Azure AD. Ele representa um ID único para a conta do Azure Mapas e pode ser recuperado na API de Contas do plano de gerenciamento do Azure Mapas. Para mais informações sobre o uso da segurança Microsoft Entra ID em Azure Mapas, veja Gerencie autenticação em Azure Mapas. |
|
| Accept-Language |
string |
Idioma no qual os resultados da pesquisa devem ser retornados. |
Corpo da solicitação
| Nome | Tipo | Description |
|---|---|---|
| batchItems |
A lista de consultas a serem processadas. |
Respostas
| Nome | Tipo | Description |
|---|---|---|
| 200 OK |
A solicitação foi bem-sucedida. |
|
| Other Status Codes |
Uma resposta de erro inesperada. Cabeçalhos x-ms-error-code: string |
Segurança
AadToken
Estes são os fluxos Microsoft Entra OAuth 2.0. Quando combinado com o controle de acesso baseado em funções Azure , pode ser usado para controlar o acesso às APIs REST Azure Mapas. Controles de acesso baseados em função do Azure são usados para designar acesso a uma ou mais contas ou subrecursos de recursos do Azure Mapas. Qualquer usuário, grupo ou principal de serviço pode receber acesso via um papel embutido ou um papel personalizado composto por uma ou mais permissões para Azure Mapas APIs REST.\n\nPara implementar cenários, recomendamos visualizar conceitos autenticação. Em resumo, essa definição de segurança fornece uma solução para modelagem de aplicações(ões) por meio de objetos capazes de controle de acesso em APIs e escopos específicos.\n\n#### Notas\n* Esta definição de segurança exige o uso do cabeçalho x-ms-client-id para indicar a qual Azure Mapas recurso o aplicativo está solicitando acesso. Isso pode ser adquirido da API de gerenciamento Maps.\n* \nO Authorization URL é específico para a instância Azure nuvem pública. As nuvens soberanas possuem URLs de Autorização e configurações de Microsoft Entra ID únicas. \n* \nO controle de acesso baseado em função Azure é configurado a partir do plano de gerenciamento Azure via portal Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.\n* \nUso do Azure Mapas Web SDK permite a configuração de uma aplicação baseada em configuração para múltiplos casos de uso.\n* Para mais informações sobre plataforma de identidade da Microsoft, veja plataforma de identidade da Microsoft visão geral.
Tipo:
oauth2
Flow:
implicit
URL de Autorização:
https://login.microsoftonline.com/common/oauth2/authorize
Escopos
| Nome | Description |
|---|---|
| https://atlas.microsoft.com/.default |
subscription-key
Esta é uma chave compartilhada que é provisionada quando você Criar uma conta Azure Mapas no portal Azure ou usando PowerShell, CLI, SDKs do Azure ou API REST.\n\n Com essa chave, qualquer aplicativo pode acessar toda a API REST. Em outras palavras, essa chave pode ser usada como uma chave mestra na conta em que são emitidas.\n\n Para aplicações publicamente expostas, nossa recomendação é usar a abordagem confidenciais de aplicativos clientes para acessar APIs REST Azure Mapas e assim 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 List SAS no recurso Azure Mapas através do plano de gerenciamento Azure via portal Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.\n\n Com este token, qualquer aplicativo está autorizado a acessar com Azure controles de acesso baseados em funções e controle detalhado da expiração, taxa e região(s) de uso do token específico. Em outras palavras, o Token SAS pode ser usado para permitir que aplicações controlem o acesso de forma mais segura do que a chave compartilhada.\n\n Para aplicações publicamente expostas, nossa recomendação é configurar uma lista específica de origens permitidas no recurso da conta Map para limitar abusos de renderização e renovar regularmente o Token SAS.
Tipo:
apiKey
Em:
header
Exemplos
A Geocoding Batch API call containing 2 Geocoding queries
Solicitação de exemplo
POST {endpoint}/geocode:batch?api-version=2026-01-01
{
"batchItems": [
{
"addressLine": "15127 NE 24th Street, Redmond, WA 98052",
"top": 2,
"optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
},
{
"query": "Pike Pl",
"locality": "Seattle",
"top": 3
}
]
}
Resposta de exemplo
{
"summary": {
"successfulRequests": 1,
"totalRequests": 2
},
"batchItems": [
{
"optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B",
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"type": "Address",
"confidence": "High",
"matchCodes": [
"Good"
],
"address": {
"locality": "Redmond",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King County"
}
],
"countryRegion": {
"ISO": "US",
"name": "United States"
},
"postalCode": "98052",
"formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
"streetName": "NE 24th St",
"streetNumber": "15127",
"addressLine": "15127 NE 24th St"
},
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.138669,
47.630359
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display",
"Route"
]
},
{
"geometry": {
"type": "Point",
"coordinates": [
-122.1387383,
47.630563
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-122.138669,
47.630359
]
},
"bbox": [
-122.14631082421619,
47.62649628242932,
-122.1310271757838,
47.634221717570675
]
}
]
},
{
"error": {
"code": "Conflicting Parameters",
"message": "When 'query' is present, only the following parameters are valid: 'bbox, location, view, top'. 'locality' was passed"
}
}
]
}
Definições
| Nome | Description |
|---|---|
| Address |
O endereço do resultado |
|
Address |
O nome da subdivisão no país ou região para um endereço. |
|
Address |
País ou região com seu nome e código ISO. |
|
Azure. |
O objeto de erro. |
|
Azure. |
Uma resposta que contém detalhes do erro. |
|
Azure. |
Um objeto que contém informações mais específicas sobre o erro. De acordo com as diretrizes Azure API REST - https://aka.ms/AzureRestApiGuidelines#handling-errors. |
|
Calculation |
O método que foi usado para calcular o ponto de código geográfico. |
|
Confidence |
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. |
|
Error |
As informações adicionais do erro de gerenciamento de recursos. |
|
Error |
O detalhe do erro. |
|
Feature |
Especifica o tipo de |
|
Features |
Um objeto de destaque. |
|
Features |
Propriedades da característica. |
|
Feature |
O tipo de um recurso deve ser Feature. |
|
Geocode |
Um ponto de geocódigo. |
|
Geocoding |
A lista de consultas/solicitações de geocodificação de endereço a serem processadas. A lista pode conter no máximo 100 consultas e deve conter pelo menos 1 consulta. |
|
Geocoding |
Objeto De Consulta em Lote |
|
Geocoding |
Esse objeto é retornado de uma chamada de serviço do Lote de Geocodificação bem-sucedida. |
|
Geocoding |
Um item de resposta em lote. |
|
Geocoding |
Resumo da solicitação em lote |
|
Geo |
Especifica o tipo de |
|
Geo |
Um tipo de geometria de |
| Intersection |
O endereço do resultado. |
|
Match |
Um enum representando o código de correspondência. |
|
Usage |
Um enum representando o tipo de uso. |
Address
O endereço do resultado
| Nome | Tipo | Description |
|---|---|---|
| addressLine |
string |
AddressLine que inclui o nome e o número da rua |
| 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. |
|
| countryRegion |
País ou região com seu nome e código ISO. |
|
| formattedAddress |
string |
Propriedade de endereço formatado |
| intersection |
O endereço do resultado. |
|
| locality |
string |
Propriedade de localidade |
| neighborhood |
string |
Propriedade do bairro |
| postalCode |
string |
Propriedade do CEP |
| streetName |
string |
O nome da rua de formattedAddress |
| streetNumber |
string |
O número na rua, se disponível, de formattedAddress |
AddressAdminDistrictsItem
O nome da subdivisão no país ou região para um endereço.
| Nome | Tipo | Description |
|---|---|---|
| name |
string |
O nome do campo adminDistrict correspondente, For adminDistrict[0], pode ser o nome completo do estado, como Washington, For adminDistrict[1], este pode ser o nome completo do condado |
| shortName |
string |
O nome curto do campo adminDistrict correspondente, For adminDistrict[0], pode ser um nome curto de estado, como WA, For adminDistrict[1], esse pode ser o nome curto do município |
AddressCountryRegion
País ou região com seu nome e código ISO.
| Nome | Tipo | Description |
|---|---|---|
| ISO |
string |
ISO do país/região |
| name |
string |
nome do país/região |
Azure.Core.Foundations.Error
O objeto de erro.
| Nome | Tipo | Description |
|---|---|---|
| code |
string |
Um de um conjunto definido pelo servidor de códigos de erro. |
| details |
Uma matriz de detalhes sobre erros específicos que levaram a esse erro relatado. |
|
| innererror |
Um objeto que contém informações mais específicas do que o objeto atual sobre o erro. |
|
| message |
string |
Uma representação legível pelo ser humano do erro. |
| target |
string |
O destino do erro. |
Azure.Core.Foundations.ErrorResponse
Uma resposta que contém detalhes do erro.
| Nome | Tipo | Description |
|---|---|---|
| error |
O objeto de erro. |
Azure.Core.Foundations.InnerError
Um objeto que contém informações mais específicas sobre o erro. De acordo com as diretrizes Azure API REST - https://aka.ms/AzureRestApiGuidelines#handling-errors.
| Nome | Tipo | Description |
|---|---|---|
| code |
string |
Um de um conjunto definido pelo servidor de códigos de erro. |
| innererror |
Erro interno. |
CalculationMethodEnum
O método que foi usado para calcular o ponto de código geográfico.
| Valor | Description |
|---|---|
| Interpolation |
O ponto de geocódigo foi correspondido a um ponto em uma estrada usando interpolação. |
| InterpolationOffset |
O ponto de geocódigo foi correspondido a um ponto em uma estrada usando interpolação com um deslocamento adicional para deslocar o ponto para o lado da rua. |
| Parcel |
O ponto de geocódigo foi correspondido ao centro de um lote. |
| Rooftop |
O ponto de geocódigo foi combinado com o telhado de um edifício. |
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.
| Valor | Description |
|---|---|
| High |
Se a confiança estiver definida como Se uma solicitação incluir um local ou uma vista, a classificação poderá ser alterada adequadamente. Por exemplo, uma consulta de localização para "Paris" retorna "Paris, França" e "Paris, TX" ambos com |
| Medium |
Em algumas situações, a correspondência retornada pode não estar no mesmo nível das informações fornecidas na solicitação. Por exemplo, uma solicitação pode especificar informações de endereço e o serviço de geocódigo pode corresponder apenas a um código postal. Nesse caso, se o serviço de geocódigo tiver uma confiança de que o CEP corresponde aos dados, a confiança será definida como Se as informações de localização na consulta forem ambíguas e não houver informações adicionais para classificar as localizações (como a localização do utilizador ou a importância relativa da localização), a confiança será definida como Se as informações de localização na consulta não fornecerem informações suficientes para geocodificar um local específico, um valor de localização menos preciso poderá ser retornado e a confiança será definida como |
| Low |
Baixo |
ErrorAdditionalInfo
As informações adicionais do erro de gerenciamento de recursos.
| Nome | Tipo | Description |
|---|---|---|
| info |
object |
As informações adicionais. |
| type |
string |
O tipo de informação adicional. |
ErrorDetail
O detalhe do erro.
| Nome | Tipo | Description |
|---|---|---|
| additionalInfo |
As informações adicionais do erro. |
|
| code |
string |
O código do erro. |
| details |
Os detalhes do erro. |
|
| message |
string |
A mensagem de erro. |
| target |
string |
O destino do erro. |
FeatureCollectionEnum
Especifica o tipo de GeoJSON. O único tipo de objeto com suporte é FeatureCollection. Para obter mais informações, consulte RFC 7946.
| Valor | Description |
|---|---|
| FeatureCollection |
Especifica o tipo de objeto |
FeaturesItem
Um objeto de destaque.
FeaturesItemProperties
Propriedades da característica.
| Nome | Tipo | Description |
|---|---|---|
| address |
O endereço do resultado |
|
| confidence |
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. |
|
| geocodePoints |
Uma coleção de pontos de código geográfico que diferem em como eles foram calculados e seu uso sugerido. |
|
| matchCodes |
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 Da mesma forma, um local geocodificado com códigos de correspondência de Os valores possíveis são:
|
|
| type |
string |
Um dos: * Endereço * BloqueioEstrada * InterseçãoEstrada * Bairro * Lugar Povoado * CEP1 * DivisãoAdministrativa1 * DivisãoAdministrativa2 * PaísRegião |
FeatureTypeEnum
O tipo de um recurso deve ser Feature.
| Valor | Description |
|---|---|
| Feature |
Especifica o tipo de objeto |
GeocodePointsItem
Um ponto de geocódigo.
GeocodingBatchRequestBody
A lista de consultas/solicitações de geocodificação de endereço a serem processadas. A lista pode conter no máximo 100 consultas e deve conter pelo menos 1 consulta.
| Nome | Tipo | Description |
|---|---|---|
| batchItems |
A lista de consultas a serem processadas. |
GeocodingBatchRequestItem
Objeto De Consulta em Lote
| Nome | Tipo | Valor padrão | Description |
|---|---|---|---|
| addressLine |
string |
A linha de rua oficial de um endereço relativo à área, conforme especificado pelas propriedades localidade ou postalCode. O uso típico desse elemento seria fornecer um endereço ou qualquer endereço oficial. Esse parâmetro não deve ser usado quando o |
|
| adminDistrict |
string |
A parte da subdivisão do país de um endereço, como WA. Esse parâmetro não deve ser usado quando o |
|
| adminDistrict2 |
string |
O condado para o endereço estruturado, como King. Esse parâmetro não deve ser usado quando o |
|
| adminDistrict3 |
string |
A área nomeada para o endereço estruturado. Esse parâmetro não deve ser usado quando o |
|
| bbox |
number[] (double) |
Uma área retangular na Terra definida como um objeto de caixa delimitadora. Os lados dos retângulos são definidos por valores de longitude e latitude. Para obter mais informações, consulte Tipos de localização e área. Quando você especifica esse parâmetro, a área geográfica é levada em conta ao calcular os resultados de uma consulta de local. Exemplo: [lon1, lat1, lon2, lat2] |
|
| coordinates |
number[] (double) |
Um ponto na Terra especificado como longitude e latitude. Quando você especifica esse parâmetro, a localização do usuário é levada em consideração e os resultados retornados podem ser mais relevantes para o usuário. Exemplo: [lon, lat] |
|
| countryRegion |
string |
Sinalize o resultado da geocodificação para um código de região/país ISO 3166-1 Alfa-2 especificado, por exemplo, FR. Esse parâmetro não deve ser usado quando o |
|
| locality |
string |
A parte da localidade de um endereço, como Seattle. Esse parâmetro não deve ser usado quando o |
|
| optionalId |
string |
ID da solicitação que seria mostrada no batchItem correspondente |
|
| postalCode |
string |
A parte do código postal de um endereço. Esse parâmetro não deve ser usado quando o |
|
| query |
string |
Uma cadeia de caracteres que contém informações sobre um local, como um endereço ou nome de ponto de referência. |
|
| top |
integer (int32) minimum: 1maximum: 20 |
5 |
Número máximo de respostas que serão retornadas. Padrão: 5, mínimo: 1 e máximo: 20. |
| view |
string |
auto |
Uma cadeia de caracteres que especifica uma de código de região/país iso 3166-1 alfa-2 do ISO 3166-1 . Isso alterará as bordas e rótulos contestados geopolíticos para se alinharem com a região de usuário especificada. |
GeocodingBatchResponse
Esse objeto é retornado de uma chamada de serviço do Lote de Geocodificação bem-sucedida.
| Nome | Tipo | Description |
|---|---|---|
| batchItems |
Matriz que contém os resultados do lote. |
|
| nextLink |
string |
É o link para a próxima página dos recursos retornados. Se for a última página, não este campo. |
| summary |
Resumo da solicitação em lote |
GeocodingBatchResponseItem
Um item de resposta em lote.
| Nome | Tipo | Description |
|---|---|---|
| error |
O detalhe do erro. |
|
| features |
Uma série de recursos retornados da consulta. |
|
| nextLink |
string |
É o link para a próxima página dos recursos retornados. Se for a última página, não este campo. |
| optionalId |
string |
id do batchItem que seria o mesmo que a ID na solicitação |
| type |
Especifica o tipo de |
GeocodingBatchResponseSummary
Resumo da solicitação em lote
| Nome | Tipo | Description |
|---|---|---|
| successfulRequests |
integer (int32) |
Número de solicitações bem-sucedidas no lote |
| totalRequests |
integer (int32) |
Número total de solicitações no lote |
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.
| Valor | Description |
|---|---|
| Point |
|
| MultiPoint |
|
| LineString |
|
| MultiLineString |
|
| Polygon |
|
| MultiPolygon |
|
| GeometryCollection |
|
| Feature |
|
| FeatureCollection |
|
GeoJsonPoint
Um tipo de geometria de GeoJSON Point válido. Consulte RFC 7946 para obter detalhes.
Intersection
O endereço do resultado.
| Nome | Tipo | Description |
|---|---|---|
| baseStreet |
string |
Rua primária para o local. |
| displayName |
string |
Nome completo da interseção. |
| intersectionType |
string |
Tipo de interseção. |
| secondaryStreet1 |
string |
A primeira rua de interseção. |
| secondaryStreet2 |
string |
Se houver, a segunda rua de interseção. |
MatchCodesEnum
Um enum representando o código de correspondência.
| Valor | Description |
|---|---|
| Good |
Bom |
| Ambiguous |
Ambíguo |
| UpHierarchy |
UpHierarchy |
UsageTypeEnum
Um enum representando o tipo de uso.
| Valor | Description |
|---|---|
| Display |
Display |
| Route |
Route |