Partilhar via


Search - Get Reverse Geocoding

Use para obter um endereço e informações de localização a partir de coordenadas de longitude e latitude.
A API Get Reverse Geocoding é uma solicitação de GET HTTP usada para traduzir uma coordenada (exemplo: 37.786505, -122.3862) em um endereço de rua compreensível por humanos. Útil em aplicações de rastreamento onde você recebe um feed GPS do dispositivo ou ativo e deseja saber o endereço associado às coordenadas. Esse ponto de extremidade retornará informações de endereço para uma determinada coordenada.

GET {endpoint}/reverseGeocode?api-version=2026-01-01&coordinates={coordinates}
GET {endpoint}/reverseGeocode?api-version=2026-01-01&coordinates={coordinates}&resultTypes={resultTypes}&view={view}

Parâmetros do URI

Name Em Necessário Tipo Description
endpoint
path True

string

api-version
query True

string

minLength: 1

A versão da API a utilizar para esta operação.

coordinates
query True

number[]

As coordenadas do local que você deseja reverter o geocódigo. Exemplo: &coordinates=lon,lat

resultTypes
query

ReverseGeocodingResultTypeEnum[]

Especifique os tipos de entidade que você deseja 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 localização será retornada na resposta. O valor padrão é todas as entidades possíveis. Uma lista separada por vírgulas dos tipos de entidade selecionados entre as opções a seguir.

  • Morada
  • Bairro
  • PopulatedPlace
  • Código postal1
  • AdminDivision1
  • AdminDivision2
  • País/Região

Estes tipos de entidades 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 encontradas para ambos os tipos, somente as informações da entidade Address serão retornadas na resposta.

view
query

string

Uma cadeia de caracteres que representa um código de região/país ISO 3166-1 Alpha-2 . Isso alterará fronteiras e rótulos disputados geopoliticamente para se alinhar com a região de usuário especificada. Por padrão, o parâmetro View é definido como "Auto", mesmo que você não o tenha definido na solicitação.

Consulte de Visualizações Suportadas para obter detalhes e ver as Visualizações disponíveis.

Cabeçalho do Pedido

Name Necessário Tipo Description
x-ms-client-id

string

Especifica qual a conta destinada a ser usada em conjunto com o modelo de segurança do Azure AD. Representa um ID único para a conta Azure Maps e pode ser recuperado na API de Contas do plano de gestão do Azure Maps. Para mais informações sobre o uso da segurança Microsoft Entra ID em Azure Maps, consulte Gerir autenticação em Azure Maps.

Accept-Language

string

Idioma em que os resultados da pesquisa devem ser retornados.

Consulte de idiomas suportados para obter detalhes.

Respostas

Name Tipo Description
200 OK

GeocodingResponse

O pedido foi bem-sucedido.

Media Types: "application/geo+json", "application/json"

Other Status Codes

Azure.Core.Foundations.ErrorResponse

Uma resposta de erro inesperada.

Media Types: "application/geo+json", "application/json"

Cabeçalhos

x-ms-error-code: string

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 utilizador, grupo ou principal de serviço pode receber acesso através de um papel incorporado ou de um papel personalizado composto por uma ou mais permissões para Azure Maps APIs REST.\n\nPara implementar cenários, recomendamos consultar conceitos autenticação. Em resumo, esta definição de segurança fornece uma solução para modelar aplicações(ões) através de objetos capazes de controlo de acesso em APIs e escopos específicos.\n\n#### Notas\n* Esta definição de segurança exige a utilização do cabeçalho x-ms-client-id para indicar a que Azure Maps recurso a aplicação está a pedir acesso. Isto pode ser adquirido da API de gestão Maps.\n* \nO Authorization URL é específico para a instância Azure cloud pública. As clouds soberanas têm URLs de Autorização e configurações de Microsoft Entra ID únicas. \n* \nO controlo de acesso Azure baseado em funções é configurado a partir do plano de gestão Azure via portal Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.\n* \nUtilização do Azure Maps Web SDK permite a configuração de uma aplicação para múltiplos casos de uso.\n* Para mais informações sobre plataforma de identidades da Microsoft, consulte plataforma de identidades da Microsoft visão geral.

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

Âmbitos

Name Description
https://atlas.microsoft.com/.default

subscription-key

Esta é uma chave partilhada que é provisionada quando Cria uma conta Azure Maps no portal Azure ou usando PowerShell, CLI, SDKs do Azure ou API REST.\n\n Com esta chave, qualquer aplicação pode aceder a toda a API REST. Ou seja, esta chave pode ser usada como chave mestra na conta onde são emitidas.\n\n Para aplicações expostas publicamente, a nossa recomendação é usar a abordagem confidenciais de aplicações cliente para aceder às APIs REST Azure Maps para que a sua chave possa ser armazenada de forma segura.

Tipo: apiKey
Em: header

SAS Token

Este é um token de assinatura de acesso partilhado criado a partir da operação List SAS no recurso Azure Maps através do plano de gestão Azure via portal Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.\n\n Com este token, qualquer aplicação está autorizada a aceder com Azure controlos de acesso baseados em funções e controlo minucioso da expiração, taxa e região(s) de utilização para o token em questão. Por outras palavras, o Token SAS pode ser usado para permitir que aplicações controlem o acesso de forma mais segura do que a chave partilhada.\n\n Para aplicações publicamente expostas, a 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

Search point -122.138681, 47.630358

Pedido de amostra

GET {endpoint}/reverseGeocode?api-version=2026-01-01&coordinates=-122.138681,47.630358

Resposta da amostra

Content-Type: application/geo+json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "address": {
          "countryRegion": {
            "name": "United States"
          },
          "adminDistricts": [
            {
              "name": "Washington",
              "shortName": "WA"
            },
            {
              "name": "King County",
              "shortName": "King Co."
            }
          ],
          "formattedAddress": "15127 NE 24th St, Redmond, Washington 98052",
          "streetName": "NE 24th St",
          "streetNumber": "15127",
          "locality": "Redmond",
          "postalCode": "98052",
          "addressLine": "15127 NE 24th St"
        },
        "type": "Address",
        "confidence": "Medium",
        "matchCodes": [
          "Good"
        ],
        "geocodePoints": [
          {
            "geometry": {
              "type": "Point",
              "coordinates": [
                -122.138681,
                47.630358
              ]
            },
            "calculationMethod": "Rooftop",
            "usageTypes": [
              "Display"
            ]
          },
          {
            "geometry": {
              "type": "Point",
              "coordinates": [
                -122.1386787,
                47.6302179
              ]
            },
            "calculationMethod": "Rooftop",
            "usageTypes": [
              "Route"
            ]
          }
        ]
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.138681,
          47.630358
        ]
      },
      "bbox": [
        -122.14632282407,
        47.626495282429325,
        -122.13103917593001,
        47.63422071757068
      ]
    }
  ]
}

Definições

Name Description
Address

O endereço do resultado

AddressAdminDistrictsItem

O nome da subdivisão no país ou região de um endereço.

AddressCountryRegion

País ou região com o seu nome e código ISO.

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 esse valor com o código de correspondência para determinar 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 especificada.

FeatureCollectionEnum

Especifica o tipo de GeoJSON. O único tipo de objeto suportado é FeatureCollection. Para obter mais informações, consulte RFC 7946.

FeaturesItem

Um objeto de funcionalidade.

FeaturesItemProperties

Propriedades da funcionalidade.

FeatureTypeEnum

O tipo de recurso deve ser Recurso.

GeocodePointsItem

Um ponto de geocódigo.

GeocodingResponse

Este objeto é retornado de uma chamada de Geocoding bem-sucedida

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

O endereço do resultado.

MatchCodesEnum

Um enum que representa o código de correspondência.

ReverseGeocodingResultTypeEnum

Um enum que representa o tipo de resultado de geocodificação inversa.

UsageTypeEnum

Um enum que representa o tipo de uso.

Address

O endereço do resultado

Name Tipo Description
addressLine

string

AddressLine que inclui o nome e o número da rua

adminDistricts

AddressAdminDistrictsItem[]

O nome da subdivisão no país ou região de um endereço. Este 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

AddressCountryRegion

País ou região com o seu nome e código ISO.

formattedAddress

string

Propriedade de endereço formatado

intersection

Intersection

O endereço do resultado.

locality

string

Propriedade de localidade

neighborhood

string

Propriedade do bairro

postalCode

string

Propriedade do código postal

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 de um endereço.

Name Tipo Description
name

string

O nome para o campo adminDistrict correspondente, Para adminDistrict[0], este poderia ser o nome completo do estado, como Washington, Para adminDistrict[1], este poderia ser o nome completo do condado

shortName

string

O nome curto para o campo adminDistrict correspondente, Para adminDistrict[0], este poderia ser o nome curto do estado, como WA, Para adminDistrict[1], este poderia ser o nome curto do condado

AddressCountryRegion

País ou região com o seu nome e código ISO.

Name 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.

Name Tipo Description
code

string

Um de um conjunto de códigos de erro definido pelo servidor.

details

Azure.Core.Foundations.Error[]

Uma matriz de detalhes sobre erros específicos que levaram a esse erro relatado.

innererror

Azure.Core.Foundations.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 por humanos do erro.

target

string

O alvo do erro.

Azure.Core.Foundations.ErrorResponse

Uma resposta contendo detalhes do erro.

Name Tipo Description
error

Azure.Core.Foundations.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 Azure diretrizes da API REST - https://aka.ms/AzureRestApiGuidelines#handling-errors.

Name Tipo Description
code

string

Um de um conjunto de códigos de erro definido pelo servidor.

innererror

Azure.Core.Foundations.InnerError

Erro interno.

CalculationMethodEnum

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

Valor Description
Interpolation

O ponto de geocódigo foi combinado com um ponto em uma estrada usando interpolação.

InterpolationOffset

O ponto de geocódigo foi combinado com 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 combinado com o centro de uma parcela.

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 da localização geocodificada é 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 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.

Valor Description
High

Se a confiança estiver definida como High, uma ou mais partidas fortes foram encontradas. As correspondências de confiança múltipla High são classificadas em ordem classificada por importância, quando aplicável. Por exemplo, os pontos de referência têm importância, mas os endereços não.

Se uma solicitação incluir um local ou uma exibição, a classificação pode mudar apropriadamente. Por exemplo, uma consulta de localização para "Paris" retorna "Paris, França" e "Paris, TX" ambos com High confiança. "Paris, França" é sempre classificado em primeiro lugar devido à importância, a menos que uma localização do usuário indique que o usuário está em ou muito perto de Paris, TX ou a visualização do mapa indique que o usuário está pesquisando nessa área.

Medium

Em algumas situações, a correspondência devolvida 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 geocodificação só pode corresponder a um código postal. Nesse caso, se o serviço de geocódigo tiver uma confiança de que o código postal corresponde aos dados, a confiança será definida como Medium e o código de correspondência será definido para UpHierarchy especificar que ele não poderia corresponder a todas as informações e teve que pesquisar na hierarquia superior.

Se as informações de localização na consulta forem ambíguas e não houver informações adicionais para classificar os locais (como a localização do usuário ou a importância relativa do local), a confiança será definida como Medium. Por exemplo, uma consulta de localização para "148th Ave, Bellevue" pode retornar "148th Ave SE" e "148th Ave NE" ambos com Medium confiança.

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 Medium. Por exemplo, se um endereço for fornecido, mas não for encontrada uma correspondência para o número da casa, o resultado do geocódigo com um tipo de entidade Roadblock poderá ser retornado.

Low

Baixo

FeatureCollectionEnum

Especifica o tipo de GeoJSON. O único tipo de objeto suportado é FeatureCollection. Para obter mais informações, consulte RFC 7946.

Valor Description
FeatureCollection

Especifica o tipo de objeto GeoJSONFeatureCollection.

FeaturesItem

Um objeto de funcionalidade.

Name Tipo Description
bbox

number[] (double)

Caixa delimitadora. Projeção utilizada - EPSG:3857. Consulte RFC 7946 para obter detalhes.

geometry

GeoJsonPoint

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

id

string

ID do recurso retornado

properties

FeaturesItemProperties

Propriedades da funcionalidade.

type

FeatureTypeEnum

O tipo de recurso deve ser Recurso.

FeaturesItemProperties

Propriedades da funcionalidade.

Name Tipo Description
address

Address

O endereço do resultado

confidence

ConfidenceEnum

O nível de confiança de que o resultado da localização geocodificada é 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 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.

geocodePoints

GeocodePointsItem[]

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

matchCodes

MatchCodesEnum[]

Um ou mais valores de código de correspondência 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 geocódigo foi encontrado para as informações de localização e que o serviço de geocódigo não tinha 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 geocódigo que correspondesse a todas as informações de localização fornecidas, de modo que o serviço de geocódigo teve que pesquisar hierarquia superior e encontrar várias correspondências nesse nível. Um exemplo de Ambiguous e UpHierarchy resultado é quando você fornece informações completas de endereço, mas o serviço de geocodificação não consegue localizar uma correspondência para o endereço 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 partida ou todas as partidas retornadas são consideradas partidas fortes. Por exemplo, uma consulta para Nova York retorna várias correspondências Boas.

Ambiguous: A localização faz parte de um conjunto de possíveis correspondências. Por exemplo, quando você consulta o endereço 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: A localização representa um movimento para cima na 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 não for possível encontrar uma correspondência para o endereço solicitado, poderá ser devolvido um código de correspondência de UpHierarchy com um tipo de entidade RoadBlock.

type

string

Um deus: * Morada * Estrada * Interseção Rodoviária * Bairro * Povoado * Código Postal 1 * DivisãoAdministrativa1 * DivisãoAdministrativa2 * PaísRegião

FeatureTypeEnum

O tipo de recurso deve ser Recurso.

Valor Description
Feature

Especifica o tipo de objeto GeoJSON Feature.

GeocodePointsItem

Um ponto de geocódigo.

Name Tipo Description
calculationMethod

CalculationMethodEnum

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

geometry

GeoJsonPoint

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

usageTypes

UsageTypeEnum[]

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

GeocodingResponse

Este objeto é retornado de uma chamada de Geocoding bem-sucedida

Name Tipo Description
features

FeaturesItem[]

Uma série de funcionalidades retornadas da consulta.

nextLink

string

O é o link para a próxima página dos recursos retornados. Se for a última página, não há este campo.

type

FeatureCollectionEnum

Especifica o tipo de GeoJSON. O único tipo de objeto suportado é FeatureCollection. Para obter mais informações, consulte RFC 7946.

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

GeoJSON Point geometria.

MultiPoint

GeoJSON MultiPoint geometria.

LineString

GeoJSON LineString geometria.

MultiLineString

GeoJSON MultiLineString geometria.

Polygon

GeoJSON Polygon geometria.

MultiPolygon

GeoJSON MultiPolygon geometria.

GeometryCollection

GeoJSON GeometryCollection geometria.

Feature

GeoJSON Feature objeto.

FeatureCollection

GeoJSON FeatureCollection objeto.

GeoJsonPoint

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

Name Tipo Description
bbox

number[] (double)

Caixa delimitadora. Projeção utilizada - EPSG:3857. Consulte RFC 7946 para obter detalhes.

coordinates

number[] (double)

Um Position é uma matriz de números com dois ou mais elementos. Os dois primeiros elementos são longitude e latitude, precisamente nesta ordem. de Altitude/Elevação é um terceiro elemento opcional. Consulte RFC 7946 para obter detalhes.

type string:

Point

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.

Intersection

O endereço do resultado.

Name Tipo Description
baseStreet

string

Rua principal para o local.

displayName

string

Nome completo do cruzamento.

intersectionType

string

Tipo de intersecção.

secondaryStreet1

string

A primeira rua que se cruza.

secondaryStreet2

string

Se houver, a segunda rua que se cruza.

MatchCodesEnum

Um enum que representa o código de correspondência.

Valor Description
Good

Bom

Ambiguous

Ambíguo

UpHierarchy

UpHierarchy

ReverseGeocodingResultTypeEnum

Um enum que representa o tipo de resultado de geocodificação inversa.

Valor Description
Address

Morada

Neighborhood

Bairro

PopulatedPlace

PopulatedPlace

Postcode1

Código postal1

AdminDivision1

AdminDivision1

AdminDivision2

AdminDivision2

CountryRegion

País/Região

UsageTypeEnum

Um enum que representa o tipo de uso.

Valor Description
Display

Ecrã

Route

Percurso