Search - Get Reverse Geocoding Batch
API do Batch de Geocodificação Inversa
Aplica-se a: veja escalões de preço.
A API do Batch de Geocodificação Inversa envia lotes de consultas para a API de Geocodificação Inversa com apenas uma única chamada à API. A API permite que o autor da chamada crie um lote de até 100 consultas.
Submeter Pedido do Batch Síncrono
A API Síncrona é recomendada para pedidos em lote simples. Quando o serviço recebe um pedido, responderá assim que os itens do lote forem calculados e não haverá possibilidade de obter os resultados mais tarde. A API Síncrona devolverá um erro de tempo limite (uma resposta 408) se o pedido demorar mais de 60 segundos. O número de itens de lote está limitado a 100 para esta API.
POST https://atlas.microsoft.com/reverseGeocode:batch
POST Body for Batch Request
Para enviar as consultas de geocodificação inversa , irá utilizar um POST
pedido em que o corpo do pedido irá conter a batchItems
matriz no json
formato e o Content-Type
cabeçalho será definido como application/json
. Eis um corpo de pedido de exemplo que contém 2 consultas de geocodificação inversa :
{
"batchItems": [
{
"coordinates": [-122.128275, 47.639429],
"resultTypes": ["Address", "PopulatedPlace"]
},
{
"coordinates": [-122.341979399674, 47.6095253501216]
}
]
}
Um objeto batchItem de geocodificação inversa pode aceitar qualquer um dos parâmetros de URI de geocodificação inversa suportados.
O lote deve conter, pelo menos, 1 consulta.
Modelo de Resposta do Batch
A resposta do batch contém um summary
componente que indica o totalRequests
que fazia parte do pedido de lote original e successfulRequests
, por exemplo, consultas que foram executadas com êxito. A resposta do batch também inclui uma batchItems
matriz que contém uma resposta para cada consulta no pedido batch. O batchItems
irá conter os resultados na mesma ordem em que as consultas originais foram enviadas no pedido de lote. Cada item é de um dos seguintes tipos:
GeocodingResponse
- Se a consulta tiver sido concluída com êxito.Error
- Se a consulta tiver falhado. A resposta irá conter umcode
e ummessage
neste caso.
POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2024-04-01-preview
Parâmetros do URI
Name | Em | Necessário | Tipo | Description |
---|---|---|---|---|
api-version
|
query | True |
string |
Número da versão da API Azure Maps. |
Cabeçalho do Pedido
Name | Necessário | Tipo | Description |
---|---|---|---|
x-ms-client-id |
string |
Especifica a conta que se destina à utilização em conjunto com o modelo de segurança Azure AD. Representa um ID exclusivo para a conta Azure Maps e pode ser obtido a partir da API de Conta do plano de gestão Azure Maps. Para utilizar Azure AD segurança no Azure Maps veja os seguintes artigos para obter orientações. |
|
Accept-Language |
string |
Idioma no qual os resultados da pesquisa devem ser devolvidos. Consulte idiomas suportados para obter detalhes. |
Corpo do Pedido
Name | Tipo | Description |
---|---|---|
batchItems |
A lista de consultas a processar. |
Respostas
Name | Tipo | Description |
---|---|---|
200 OK |
OK |
|
Other Status Codes |
Ocorreu um erro inesperado. Headers x-ms-error-code: string |
Segurança
AADToken
Estes são os fluxos Microsoft Entra OAuth 2.0. Quando emparelhado com o controlo de acesso baseado em funções do Azure, pode ser utilizado para controlar o acesso às APIs REST Azure Maps. Os controlos de acesso baseados em funções do Azure são utilizados para designar o acesso a uma ou mais Azure Maps conta de recursos ou sub-recursos. Qualquer utilizador, grupo ou principal de serviço pode ter acesso através de uma função incorporada ou de uma função personalizada composta por uma ou mais permissões para Azure Maps APIs REST.
Para implementar cenários, recomendamos que veja os conceitos de autenticação. Em resumo, esta definição de segurança fornece uma solução para modelar aplicações através de objetos com capacidade de controlo de acesso em APIs e âmbitos específicos.
Nota
- Esta definição de segurança requer a utilização do
x-ms-client-id
cabeçalho para indicar a que Azure Maps recurso a que a aplicação está a pedir acesso. Isto pode ser adquirido na API de gestão de Mapas. - O
Authorization URL
é específico da instância da cloud pública do Azure. As clouds soberanas têm URLs de Autorização exclusivos e configurações de Microsoft Entra ID. - O controlo de acesso baseado em funções do Azure é configurado a partir do plano de gestão do Azure através de portal do Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.
- A utilização do SDK Web Azure Maps permite a configuração baseada na configuração de uma aplicação para vários casos de utilização.
- Para obter mais informações sobre plataforma de identidades da Microsoft, consulte plataforma de identidades da Microsoft descrição geral.
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
Name | Description |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
Esta é uma chave partilhada que é aprovisionada ao criar um recurso Azure Maps através do plano de gestão do Azure através de portal do Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.
Com esta chave, qualquer aplicação está autorizada a aceder a todas as APIs REST. Por outras palavras, estas podem atualmente ser tratadas como chaves mestras da conta para a qual são emitidas.
Para aplicações expostas publicamente, a nossa recomendação é utilizar o acesso servidor a servidor das APIs REST Azure Maps onde esta chave pode ser armazenada de forma segura.
Type:
apiKey
In:
header
SAS Token
Este é um token de assinatura de acesso partilhado criado a partir da operação Listar SAS no recurso Azure Maps através do plano de gestão do Azure através de portal do Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.
Com este token, qualquer aplicação está autorizada a aceder com controlos de acesso baseados em funções do Azure e controlo detalhado para a expiração, taxa e regiões de utilização para o token específico. Por outras palavras, o Token de SAS pode ser utilizado para permitir que as aplicações controlem o acesso de uma forma mais segura do que a chave partilhada.
Para aplicações expostas publicamente, a nossa recomendação é configurar uma lista específica de origens permitidas no recurso da conta de Mapa para limitar o abuso de composição e renovar regularmente o Token de SAS.
Type:
apiKey
In:
header
Exemplos
A Reverse Geocoding Batch API call containing 2 Reverse Geocoding queries
Sample Request
POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2024-04-01-preview
{
"batchItems": [
{
"coordinates": [
-122.128275,
47.639429
],
"resultTypes": [
"Address",
"PopulatedPlace"
],
"optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
},
{
"coordinates": [
-122.341979399674,
47.6095253501216
],
"optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
}
]
}
Sample Response
{
"summary": {
"successfulRequests": 1,
"totalRequests": 2
},
"batchItems": [
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"type": "Address",
"confidence": "High",
"matchCodes": [
"Good"
],
"address": {
"locality": "Redmond",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King"
}
],
"countryRegion": {
"ISO": "US",
"name": "United States"
},
"postalCode": "98052",
"formattedAddress": "1 Microsoft Way, Redmond, WA 98052",
"addressLine": "1 Microsoft Way"
},
"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": "3K5O3Y832J2YV6D7XNGUSM4ECCUGDEFN172CJQNN",
"error": {
"code": "400 Bad Request",
"message": "The provided coordinates in query are invalid, out of range, or not in the expected format"
}
}
]
}
Definições
Name | Description |
---|---|
Address |
O endereço do resultado |
Admin |
O nome da subdivisão no país ou região de um endereço. Este elemento é normalmente tratado como a subdivisão administrativa da primeira ordem, mas em alguns casos também contém a subdivisão de segunda, terceira ou quarta ordem num país, dependência ou região. |
Calculation |
O método utilizado para calcular o ponto de geocódigo. |
Confidence |
O nível de confiança de que o resultado da localização geocódigo corresponde. Utilize este valor com o código de correspondência para determinar para obter informações mais completas sobre a correspondência. 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 especificado. |
Country |
|
Error |
Informações adicionais sobre o erro de gestão de recursos. |
Error |
O detalhe do erro. |
Error |
Resposta a erros |
Feature |
O tipo de objeto FeatureCollection tem de ser FeatureCollection. |
Features |
|
Feature |
O tipo de uma funcionalidade tem de ser Funcionalidade. |
Geocode |
Uma coleção de pontos geocódigos que diferem na forma como foram calculados e na utilização sugerida. |
Geocoding |
Este objeto é devolvido a partir de uma chamada de serviço do Batch de Geocodificação bem-sucedida. |
Geocoding |
|
Geo |
Um tipo de geometria válido |
Intersection |
O endereço do resultado. |
Match |
Um ou mais correspondem aos valores de código que representam o nível de geocodificação para cada localização na resposta. Por exemplo, uma localização geocódigo com códigos de correspondência e Da mesma forma, uma localização geocodificada com códigos de correspondência de Os valores possíveis são:
|
Properties | |
Result |
Especifique os tipos de entidade que pretende na resposta. Apenas os tipos que especificar serão devolvidos. Se o ponto não puder ser mapeado para os tipos de entidade que especificar, não serão devolvidas informações de localização na resposta. O valor predefinido é todas as entidades possíveis. Uma lista separada por vírgulas de tipos de entidade selecionados nas seguintes opções.
Estes tipos de entidade são ordenados da entidade mais específica para a entidade menos específica. Quando são encontradas entidades de mais do que um tipo de entidade, só é devolvida a entidade mais específica. Por exemplo, se especificar Endereço e AdminDistrict1 como tipos de entidade e entidades foram encontrados para ambos os tipos, apenas as informações da entidade Endereço são devolvidas na resposta. |
Reverse |
A lista de consultas/pedidos de geocodificação inversas a processar. A lista pode conter um máximo de 100 consultas e tem de conter, pelo menos, 1 consulta. |
Reverse |
Objeto do Batch Query |
Summary |
Resumo do pedido de lote |
Usage |
A melhor utilização para o ponto de geocódigo.
Cada ponto de geocódigo é definido como um |
Address
O endereço do resultado
Name | Tipo | Description |
---|---|---|
addressLine |
string |
AddressLine que inclui o Nome da Rua e o Número |
adminDistricts |
O nome da subdivisão no país ou região de um endereço. Este elemento é normalmente tratado como a subdivisão administrativa da primeira ordem, mas em alguns casos também contém a subdivisão de segunda, terceira ou quarta ordem num país, dependência ou região. |
|
countryRegion | ||
formattedAddress |
string |
Propriedade Endereço Formatado |
intersection |
O endereço do resultado. |
|
locality |
string |
propriedade localidade |
neighborhood |
string |
propriedade do bairro |
postalCode |
string |
Propriedade Código Postal |
AdminDistricts
O nome da subdivisão no país ou região de um endereço. Este elemento é normalmente tratado como a subdivisão administrativa da primeira ordem, mas em alguns casos também contém a subdivisão de segunda, terceira ou quarta ordem num país, dependência ou região.
Name | Tipo | Description |
---|---|---|
name |
string |
O nome do campo adminDistrict correspondente, Para adminDistrict[0], este pode ser o nome completo do estado como Washington, For adminDistrict[1], this could be the full name of the county |
shortName |
string |
O nome abreviado para o campo adminDistrict correspondente, Para adminDistrict[0], este pode ser um nome abreviado de estado, como WA, Para adminDistrict[1], este pode ser o nome abreviado do concelho |
CalculationMethodEnum
O método utilizado para calcular o ponto de geocódigo.
Name | Tipo | Description |
---|---|---|
Interpolation |
string |
O ponto geocódigo foi correspondido a um ponto numa estrada através da interpolação. |
InterpolationOffset |
string |
O ponto geocódigo foi correspondido a um ponto numa estrada usando interpolação com um desvio adicional para deslocar o ponto para o lado da rua. |
Parcel |
string |
O ponto geocódigo foi correspondido ao centro de uma parcela. |
Rooftop |
string |
O ponto geocódigo foi combinado com o telhado de um edifício. |
ConfidenceEnum
O nível de confiança de que o resultado da localização geocódigo corresponde. Utilize este valor com o código de correspondência para determinar para obter informações mais completas sobre a correspondência.
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 especificado.
Name | Tipo | Description |
---|---|---|
High |
string |
Se a confiança estiver definida como Se um pedido incluir uma localização ou uma vista, a classificação poderá ser alterada adequadamente. Por exemplo, uma consulta de localização para "Paris" devolve "Paris, França" e "Paris, TX" ambos com |
Low |
string |
|
Medium |
string |
Em algumas situações, a correspondência devolvida pode não estar ao mesmo nível das informações fornecidas no pedido. Por exemplo, um pedido pode especificar informações de endereço e o serviço de geocódigo só pode corresponder a um código postal. Neste caso, se o serviço de geocódigo tiver a confiança de que o código postal corresponde aos dados, a confiança está definida como Se as informações de localização na consulta forem ambíguas e não existirem 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 está definida como Se as informações de localização na consulta não fornecerem informações suficientes para geocodificar uma localização específica, poderá ser devolvido um valor de localização menos preciso e a confiança está definida como |
CountryRegion
Name | Tipo | Description |
---|---|---|
ISO |
string |
ISO do país/região |
name |
string |
nome do país/região |
ErrorAdditionalInfo
Informações adicionais sobre o erro de gestão de recursos.
Name | Tipo | Description |
---|---|---|
info |
object |
As informações adicionais. |
type |
string |
O tipo de informação adicional. |
ErrorDetail
O detalhe do erro.
Name | Tipo | Description |
---|---|---|
additionalInfo |
As informações adicionais do erro. |
|
code |
string |
O código de erro. |
details |
Os detalhes do erro. |
|
message |
string |
A mensagem de erro. |
target |
string |
O destino do erro. |
ErrorResponse
Resposta a erros
Name | Tipo | Description |
---|---|---|
error |
O objeto de erro. |
FeatureCollectionEnum
O tipo de objeto FeatureCollection tem de ser FeatureCollection.
Name | Tipo | Description |
---|---|---|
FeatureCollection |
string |
FeaturesItem
Name | Tipo | Description |
---|---|---|
bbox |
number[] |
Caixa delimitadora. Projeção utilizada - EPSG:3857. Consulte RFC 7946 para obter detalhes. |
geometry |
Um tipo de geometria válido |
|
id |
string |
ID da funcionalidade devolvida |
properties | ||
type |
O tipo de uma funcionalidade tem de ser Funcionalidade. |
FeatureTypeEnum
O tipo de uma funcionalidade tem de ser Funcionalidade.
Name | Tipo | Description |
---|---|---|
Feature |
string |
GeocodePoints
Uma coleção de pontos geocódigos que diferem na forma como foram calculados e na utilização sugerida.
Name | Tipo | Description |
---|---|---|
calculationMethod |
O método utilizado para calcular o ponto de geocódigo. |
|
geometry |
Um tipo de geometria válido |
|
usageTypes |
A melhor utilização para o ponto de geocódigo.
Cada ponto de geocódigo é definido como um |
GeocodingBatchResponse
Este objeto é devolvido a partir de uma chamada de serviço do Batch de Geocodificação bem-sucedida.
Name | Tipo | Description |
---|---|---|
batchItems |
Matriz que contém os resultados do lote. |
|
nextLink |
string |
É a ligação para a página seguinte das funcionalidades devolvidas. Se for a última página, não este campo. |
summary |
Resumo do pedido de lote |
GeocodingBatchResponseItem
Name | Tipo | Description |
---|---|---|
error |
O detalhe do erro. |
|
features | ||
nextLink |
string |
É a ligação para a página seguinte das funcionalidades devolvidas. Se for a última página, não este campo. |
optionalId |
string |
id do batchItem que seria o mesmo que o ID no pedido |
type |
O tipo de objeto FeatureCollection tem de ser FeatureCollection. |
GeoJsonPoint
Um tipo de geometria válido GeoJSON Point
. Consulte RFC 7946 para obter detalhes.
Name | Tipo | Description |
---|---|---|
bbox |
number[] |
Caixa delimitadora. Projeção utilizada - EPSG:3857. Consulte RFC 7946 para obter detalhes. |
coordinates |
number[] |
A |
type |
string:
Point |
Especifica o |
Intersection
O endereço do resultado.
Name | Tipo | Description |
---|---|---|
baseStreet |
string |
Rua primária para a localização. |
displayName |
string |
Nome completo da interseção. |
intersectionType |
string |
Tipo de interseção. |
secondaryStreet1 |
string |
A primeira rua de intersecção. |
secondaryStreet2 |
string |
Se houver, a segunda rua de intersecção. |
MatchCodesEnum
Um ou mais correspondem aos valores de código que representam o nível de geocodificação para cada localização na resposta.
Por exemplo, uma localização geocódigo com códigos de correspondência e Good
Ambiguous
significa que foi encontrada mais do que uma localização de geocódigo para as informações de localização e que o serviço de geocódigo não tinha a hierarquia de pesquisa para encontrar uma correspondência.
Da mesma forma, uma localização geocodificada com códigos de correspondência de Ambiguous
e UpHierarchy
implica que não foi possível encontrar uma localização de geocódigo que correspondesse a todas as informações de localização fornecidas, pelo que o serviço de geocódigo teve de procurar na hierarquia superior e encontrou várias correspondências nesse nível. Um exemplo de aumento de um Ambiguous
UpHierarchy
resultado é quando fornece informações de endereço completas, mas o serviço de geocódigo não consegue localizar uma correspondência para o endereço de rua e, em vez disso, devolve informações para mais do que um valor RoadBlock.
Os valores possíveis são:
Good
: a localização tem apenas uma correspondência ou todas as correspondências devolvidas são consideradas correspondências fortes. Por exemplo, uma consulta para Nova Iorque devolve várias correspondências boas.
Ambiguous
: a localização é uma de um conjunto de correspondências possíveis. Por exemplo, quando consulta o endereço da rua 128 Main St., a resposta pode devolver duas localizações para a Rua Principal 128 Norte e a Rua Principal 128 Sul porque não existem informações suficientes para determinar qual a opção a escolher.
UpHierarchy
: a localização representa uma mudança para cima na hierarquia geográfica. Isto ocorre quando não foi encontrada uma correspondência para o pedido de localização, pelo que é devolvido um resultado menos preciso. Por exemplo, se não for possível encontrar uma correspondência para o endereço pedido, poderá ser devolvido um código de correspondência de com um tipo de UpHierarchy
entidade RoadBlock.
Name | Tipo | Description |
---|---|---|
Ambiguous |
string |
|
Good |
string |
|
UpHierarchy |
string |
Properties
Name | Tipo | Description |
---|---|---|
address |
O endereço do resultado |
|
confidence |
O nível de confiança de que o resultado da localização geocódigo corresponde. Utilize este valor com o código de correspondência para determinar para obter informações mais completas sobre a correspondência. 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 especificado. |
|
geocodePoints |
Uma coleção de pontos geocódigos que diferem na forma como foram calculados e na utilização sugerida. |
|
matchCodes |
Um ou mais correspondem aos valores de código que representam o nível de geocodificação para cada localização na resposta. Por exemplo, uma localização geocódigo com códigos de correspondência e Da mesma forma, uma localização geocodificada com códigos de correspondência de Os valores possíveis são:
|
|
type |
string |
Um dos seguintes:
|
ResultTypeEnum
Especifique os tipos de entidade que pretende na resposta. Apenas os tipos que especificar serão devolvidos. Se o ponto não puder ser mapeado para os tipos de entidade que especificar, não serão devolvidas informações de localização na resposta. O valor predefinido é todas as entidades possíveis. Uma lista separada por vírgulas de tipos de entidade selecionados nas seguintes opções.
- Endereço
- Bairro
- Lugar Preenchido
- Código postal1
- AdminDivision1
- AdminDivision2
- RegiãoDoPaís
Estes tipos de entidade são ordenados da entidade mais específica para a entidade menos específica. Quando são encontradas entidades de mais do que um tipo de entidade, só é devolvida a entidade mais específica. Por exemplo, se especificar Endereço e AdminDistrict1 como tipos de entidade e entidades foram encontrados para ambos os tipos, apenas as informações da entidade Endereço são devolvidas na resposta.
Name | Tipo | Description |
---|---|---|
Address |
string |
|
AdminDivision1 |
string |
|
AdminDivision2 |
string |
|
CountryRegion |
string |
|
Neighborhood |
string |
|
PopulatedPlace |
string |
|
Postcode1 |
string |
ReverseGeocodingBatchRequestBody
A lista de consultas/pedidos de geocodificação inversas a processar. A lista pode conter um máximo de 100 consultas e tem de conter, pelo menos, 1 consulta.
Name | Tipo | Description |
---|---|---|
batchItems |
A lista de consultas a processar. |
ReverseGeocodingBatchRequestItem
Objeto do Batch Query
Name | Tipo | Description |
---|---|---|
coordinates |
number[] |
As coordenadas da localização que pretende reverter o geocódigo. Exemplo: [lon,lat] |
optionalId |
string |
ID do pedido que seria apresentado no batchItem correspondente |
resultTypes |
Especifique os tipos de entidade que pretende na resposta. Apenas os tipos que especificar serão devolvidos. Se o ponto não puder ser mapeado para os tipos de entidade que especificar, não serão devolvidas informações de localização na resposta. O valor predefinido é todas as entidades possíveis. Uma lista separada por vírgulas de tipos de entidade selecionados nas seguintes opções.
Estes tipos de entidade são ordenados da entidade mais específica para a entidade menos específica. Quando são encontradas entidades de mais do que um tipo de entidade, só é devolvida a entidade mais específica. Por exemplo, se especificar Endereço e AdminDistrict1 como tipos de entidade e entidades foram encontrados para ambos os tipos, apenas as informações da entidade Endereço são devolvidas na resposta. |
|
view |
string |
Uma cadeia que especifica um código de região/país ISO 3166-1 Alpha-2. Isto irá alterar os limites e etiquetas geopolíticos contestados para se alinharem com a região de utilizador especificada. |
Summary
Resumo do pedido de lote
Name | Tipo | Description |
---|---|---|
successfulRequests |
integer |
Número de pedidos bem-sucedidos no lote |
totalRequests |
integer |
Número total de pedidos no lote |
UsageTypeEnum
A melhor utilização para o ponto de geocódigo.
Cada ponto de geocódigo é definido como um Route
ponto, um Display
ponto ou ambos.
Utilize Route
pontos se estiver a criar uma rota para a localização. Utilize Display
pontos se estiver a mostrar a localização num mapa. Por exemplo, se a localização for um parque, um Route
ponto pode especificar uma entrada para o parque onde pode entrar com um carro e um Display
ponto pode ser um ponto que especifica o centro do parque.
Name | Tipo | Description |
---|---|---|
Display |
string |
|
Route |
string |