Pesquisar um local usando os serviços de Pesquisa do Azure Mapas

  • Artigo

O serviço Pesquisa é um conjunto de APIs RESTful projetadas para ajudar os desenvolvedores a pesquisar endereços, locais e listagens de empresas por nome, categoria e outras informações geográficas. Além de oferecer suporte à geocodificação tradicional, os serviços também podem inverter endereços de geocodificação e fazer o cruzamento de ruas com base em latitudes e longitudes. Os valores de latitude e longitude retornados pela pesquisa podem ser usados como parâmetros em outros serviços do Azure Mapas, como Rota e Clima.

Este artigo demonstra como:

  • Solicitar coordenadas de latitude e longitude de um endereço (local de endereço geocodificado) usando a Pesquisa de Endereço.
  • Procurar um endereço ou POI (ponto de interesse) usando a API de Pesquisa Difusa.
  • Usar a Pesquisa Inversa de Endereço para converter o local da coordenada em um endereço.
  • Traduza a localização das coordenadas em um cruzamento compreensível por humanos usando a Reversão de Endereço de Pesquisa Entre Ruas, mais frequentemente necessário no rastreamento de aplicativos que recebem um feed de GPS de um dispositivo ou ativo, e desejam saber onde a coordenada está localizada.

Pré-requisitos

Este tutorial usa o aplicativo Postman, mas você pode escolher um ambiente de desenvolvimento de API diferente.

Solicitar latitude e longitude para um endereço (geocodificação)

O exemplo nesta seção usa Obter endereço de pesquisa para converter um endereço em coordenadas de latitude e longitude. Esse processo é chamado geocodificação. Além de retornar as coordenadas, a resposta também retorna propriedades de endereço detalhadas, como informações de rua, código postal, município e país/região.

Dica

Se você tiver um conjunto de endereços para geocodificar, use Postar Lote de Endereços de Pesquisa para enviar um lote de consultas em uma só solicitação.

  1. No aplicativo Postman, selecione Novo para criar a solicitação. Na janela Criar, selecione Solicitação HTTP. Insira um Nome de solicitação para a solicitação.

  2. Selecione o método HTTP GET na guia do construtor e insira URL a seguir. Nesta solicitação, será pesquisado um endereço específico: 400 Braod St, Seattle, WA 98109. Para esta solicitação e outras solicitações mencionadas neste artigo, substitua {Your-Azure-Maps-Subscription-key} pela sua chave de assinatura do Azure Mapas.

    https://atlas.microsoft.com/search/address/json?&subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&language=en-US&query=400 Broad St, Seattle, WA 98109

  3. Clique no botão azul Enviar. O corpo da resposta contém dados para um único local.

  4. Em seguida, pesquise um endereço que tenha mais de um local possível. Na seção Params, altere a chave query para 400 Broad, Seattle. Clique no botão azul Enviar.

    Search for address

  5. Em seguida, tente definir a chave query como 400 Broa.

  6. Selecione o botão Enviar. A resposta inclui os resultados de vários países/regiões. Para resultados geopolares para a área relevante para seus usuários, sempre adicione à solicitação o máximo possível de detalhes de local.

A Pesquisa Difusa dá suporte às pesquisas padrão de linha única e com forma livre. É recomendável o uso da API de pesquisa difusa do Azure Mapas quando não se sabe o tipo de entrada de usuário para uma solicitação de pesquisa. A entrada da consulta pode ser um endereço completo ou parcial. Também pode ser um token de POI (ponto de interesse), como um nome de POI, uma categoria de POI ou nome de marca. Além disso, para melhorar a relevância dos resultados da pesquisa, restrinja os resultados da consulta usando uma localização e raio de coordenadas ou definindo uma caixa delimitadora.

Dica

A maioria das consultas de Pesquisa tem como padrão maxFuzzyLevel=1 para melhorar o desempenho e reduzir resultados incomuns. Ajuste os níveis de imprecisão usando os parâmetros maxFuzzyLevel ou minFuzzyLevel. Para obter mais informações sobre maxFuzzyLevel e uma lista completa de todos os parâmetros opcionais, confira Parâmetros de URI de Pesquisa Difusa.

O exemplo nesta seção usa Fuzzy Search para pesquisar o mundo inteiro por pizza e, em seguida, pesquisa no escopo de um país/região específico. Finalmente, ele demonstra como usar uma localização de coordenadas e um raio para definir o escopo de uma pesquisa em uma área específica e limitar o número de resultados retornados.

Importante

Para resultados geopolares para a área relevante para seus usuários, sempre adicione o máximo possível de detalhes de local. Para obter mais informações, confira Melhores práticas para Pesquisa.

  1. No aplicativo Postman, selecione Novo para criar a solicitação. Na janela Criar, selecione Solicitação HTTP. Insira um Nome de solicitação para a solicitação.

  2. Selecione o método HTTP GET na guia do construtor e insira URL a seguir. Para esta solicitação e outras solicitações mencionadas neste artigo, substitua {Your-Azure-Maps-Subscription-key} pela sua chave de assinatura do Azure Mapas.

    https://atlas.microsoft.com/search/fuzzy/json?&api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=pizza

    Observação

    O atributo json no caminho da URL determina o formato da resposta. Este artigo usa o JSON para facilitar o uso e a legibilidade. Para localizar outros formatos de resposta com suporte, confira a format definição de parâmetro na documentação de referência de parâmetro de URI.

  3. Selecione Enviar e revise o corpo da resposta.

    A cadeia de caracteres de consulta ambígua para "pizza" retornou 10 resultados de resultado de ponto de interesse (POI) nas duas categorias "pizza" e "restaurante". Cada resultado inclui detalhes como endereço de rua, valores de latitude e longitude, vista da porta e pontos de entrada para o local. Os resultados agora são variados para esta consulta e não estão vinculados a nenhum local de referência.

    Na próxima etapa, você usará o parâmetro countrySet para especificar apenas os países/regiões para os quais seu aplicativo precisa de cobertura. Para obter uma lista completa de países/regiões com suporte, consulte Cobertura de pesquisa.

  4. O comportamento padrão é pesquisar o mundo inteiro, retornando resultados potencialmente desnecessários. Em seguida, procure pizza apenas nos Estados Unidos. Adicione a countrySet chave à seção Params e defina o valor como US. Definir a chave countrySet para US limita os resultados aos Estados Unidos.

    Search for pizza in the United States

    Os resultados agora são limitados pelo código do país e a consulta retorna as pizzarias no Brasil.

  5. Para obter uma pesquisa ainda mais direcionada, você pode pesquisar o escopo de um par de coordenadas lat/lon. O exemplo a seguir usa as coordenadas lat/lon do Seattle Space Needle. Como queremos retornar apenas os resultados dentro de um raio de 400 metros, adicionamos o parâmetro radius. Além disso, adicionamos o parâmetro limit para limitar os resultados às cinco pizzarias mais próximas.

    Na seção Params, adicione os seguintes pares de chave/valor:

    Chave Valor
    lat 47.620525
    lon -122.349274
    raio 400
    limite 5

  6. Selecione Enviar. A resposta inclui resultados para os restaurantes de pizza próximos à Agulha Espacial de Seattle.

Obter Endereços de Pesquisa Inversa converte as coordenadas em endereços legíveis por pessoas. Essa API é usada com frequência por aplicativos que consomem feeds de GPS e desejam descobrir endereços em pontos de coordenadas específicos.

Importante

Para resultados geopolares para a área relevante para seus usuários, sempre adicione o máximo possível de detalhes de local. Para obter mais informações, confira Melhores práticas para Pesquisa.

Dica

Caso tenha um conjunto de locais de coordenadas para inverter o geocódigo, use Postar Lote de Pesquisa Inversa de Endereço para enviar um lote de consultas em uma só solicitação.

Este exemplo demonstra a realização de pesquisas reversas usando alguns dos parâmetros opcionais disponíveis. Para obter a lista completa dos parâmetros opcionais, consulte Parâmetros de pesquisa inversa.

  1. No aplicativo Postman, selecione Novo para criar a solicitação. Na janela Criar, selecione Solicitação HTTP. Insira um Nome de solicitação para a solicitação.

  2. Selecione o método HTTP GET na guia do construtor e insira URL a seguir. Para esta solicitação e outras solicitações mencionadas neste artigo, substitua {Your-Azure-Maps-Subscription-key} pela sua chave de assinatura do Azure Mapas. A solicitação deve ser semelhante à seguinte URL:

    https://atlas.microsoft.com/search/address/reverse/json?api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=47.591180,-122.332700&number=1

  3. Selecione Enviar e revise o corpo da resposta. Deverá ser possível ver o resultado de uma consulta. A resposta inclui informações importantes sobre o endereço do Safeco Field.

  4. Em seguida, adicione os seguintes pares de chave/valor à seção Parâmetros:

    Chave Valor Retornos
    número 1 A resposta pode incluir o lado da rua (esquerda/direita) e também uma posição ajustada para o número.
    returnSpeedLimit true Retorna o limite de velocidade no endereço.
    returnRoadUse true Retorna os tipos de uso de estrada no endereço. Para todos os tipos de uso de estrada possíveis, consulte Tipos de uso de estrada.
    returnMatchType true Retorna o tipo de combinação. Para ver todos os valores possíveis, confira Resultados da pesquisa inversa de endereço.

    Search reverse.

  5. Selecione Enviar e revise o corpo da resposta.

  6. Em seguida, adicionamos a chave entityType e definimos seu valor como Municipality. A chave entityType substitui a chave returnMatchType na etapa anterior. returnSpeedLimit e returnRoadUse também precisam ser removidos, pois você está solicitando informações sobre o município. Para todos os tipos de entidade possíveis, consulte Tipos de entidade.

    Search reverse entityType.

  7. Selecione Enviar. Compare os resultados com os resultados retornados na etapa 5. Como o tipo de entidade solicitado agora é municipality, a resposta não inclui as informações de endereço. Além disso, o geometryId retornado pode ser usado para solicitar o polígono de limite por meio do Azure Mapas obter API de polígono de pesquisa.

Dica

Para obter mais informações sobre esses e outros parâmetros, confira Parâmetros de Pesquisa Reversa.

Este exemplo demonstra como procurar uma rua transversal com base nas coordenadas de um endereço.

  1. No aplicativo Postman, selecione Novo para criar a solicitação. Na janela Criar, selecione Solicitação HTTP. Insira um Nome de solicitação para a solicitação.

  2. Selecione o método HTTP GET na guia do construtor e insira URL a seguir. Para esta solicitação e outras solicitações mencionadas neste artigo, substitua {Your-Azure-Maps-Subscription-key} pela sua chave de assinatura do Azure Mapas. A solicitação deve ser semelhante à seguinte URL:

    https://atlas.microsoft.com/search/address/reverse/crossstreet/json?&api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=47.591180,-122.332700

    Search cross street.

  3. Selecione Enviar e revise o corpo da resposta. Observe que a resposta contém um valor crossStreet de South Atlantic Street.

Próximas etapas

Serviço Pesquisa do Azure Mapas

Práticas recomendadas para o serviço Pesquisa do Azure Mapas