Tutorial: Pesquisar pontos de interesse próximos usando o Azure Maps

Artigo
04/07/2024

Este tutorial mostra como configurar uma conta com o Azure Maps e, em seguida, utilizar as APIs do Maps para procurar um ponto de interesse. Neste tutorial, irá aprender a:

Criar uma conta do Azure Maps
Recuperar a chave de subscrição da sua conta do Google Maps
Criar uma nova página Web com a API de controlo de mapas
Utilizar o serviço de pesquisa do Maps para localizar um ponto de interesse nas proximidades

Pré-requisitos

Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

Uma conta do Azure Maps
Uma chave de subscrição

Nota

Para obter mais informações sobre autenticação no Azure Maps, consulte gerenciar autenticação no Azure Maps.

Criar um novo mapa

A API de Controle de Mapa é uma biblioteca de cliente conveniente. Esta API permite-lhe integrar facilmente o Maps na sua aplicação web. Ele esconde a complexidade das chamadas de serviço REST e aumenta sua produtividade com componentes personalizáveis. Os passos seguintes mostram como criar uma página HTML estática incorporada com a API de Controlo de Mapas.

No seu computador local, crie um novo ficheiro e dê-lhe o nome MapSearch.html.

Adicione os seguintes componentes de HTML ao ficheiro:

 <!DOCTYPE html>
 <html>
 <head>
     <title>Map Search</title>
     <meta charset="utf-8" />

     <!-- Add references to the Azure Maps Map control JavaScript and CSS files. -->
     <link rel="stylesheet" href="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.css" type="text/css" />
     <script src="https://atlas.microsoft.com/sdk/javascript/mapcontrol/3/atlas.min.js"></script>

     <!-- Add a reference to the Azure Maps Services Module JavaScript file. -->
     <script src="https://atlas.microsoft.com/sdk/javascript/service/2/atlas-service.min.js"></script>

     <script>
     function GetMap(){
         //Add Map Control JavaScript code here.
     }
     </script>

     <style>
         html,
         body {
             width: 100%;
             height: 100%;
             padding: 0;
             margin: 0;
         }

         #myMap {
             width: 100%;
             height: 100%;
         }
     </style>
 </head>
 <body onload="GetMap()">
     <div id="myMap"></div>
 </body>
 </html>

Algumas coisas a saber sobre o HTML acima:

O cabeçalho HTML inclui arquivos de recursos CSS e JavaScript hospedados pela biblioteca de Controle de Mapa do Azure.
O onload evento no corpo da página chama a GetMap função quando o corpo da página é carregado.
A GetMap função contém o código JavaScript embutido usado para acessar as APIs do Azure Maps. Ele é adicionado na próxima etapa.

Adicione o seguinte código JavaScript à função GetMap do ficheiro HTML. Substitua a cadeia de caracteres <Your Azure Maps Subscription Key> pela chave de assinatura que você copiou da sua conta do Azure Maps.
```
//Instantiate a map object
var map = new atlas.Map("myMap", {
    view: 'Auto',

    // Add your Azure Maps subscription key. https://aka.ms/am-primaryKey
    authOptions: {
        authType: 'subscriptionKey',
        subscriptionKey: '<Your Azure Maps Subscription Key>'
    }
});
```
Algumas coisas a saber sobre o JavaScript acima:
- O núcleo da função, que inicializa a API de Controle de Mapa para sua chave de GetMap conta do Azure Maps.
- atlas é o namespace que contém a API e os componentes visuais relacionados.
- atlas.Map fornece o controle para um mapa da web visual e interativo.
Guarde as alterações efetuadas ao ficheiro e abra a página HTML num browser. O mapa mostrado é o mapa mais básico que você pode fazer ligando atlas.Map usando sua chave de conta.
Na função GetMap, após inicializar o mapa, adicione o seguinte código JavaScript.
```
//Wait until the map resources are ready.
map.events.add('ready', function() {

    //Create a data source and add it to the map.
    datasource = new atlas.source.DataSource();
    map.sources.add(datasource);

    //Add a layer for rendering point data.
    var resultLayer = new atlas.layer.SymbolLayer(datasource, null, {
        iconOptions: {
            image: 'pin-round-darkblue',
            anchor: 'center',
            allowOverlap: true
        },
        textOptions: {
            anchor: "top"
        }
    });

    map.layers.add(resultLayer);
});
```
Sobre este código:
- Um ready evento é adicionado ao mapa, que é acionado quando os recursos do mapa terminam de carregar e o mapa está pronto para ser acessado.
- No manipulador de eventos de mapa ready , uma fonte de dados é criada para armazenar dados de resultados.
- É criada e anexada uma camada de símbolo à origem de dados. Esta camada especifica como os dados de resultado na fonte de dados devem ser renderizados. Nesse caso, o resultado é renderizado com um ícone de pino redondo azul escuro, centralizado sobre a coordenada de resultados que permite que outros ícones se sobreponham.
- A camada de resultados é adicionada às camadas do mapa.

Adicionar capacidades de pesquisa

Esta secção mostra como utilizar a API de Pesquisa de Mapas para encontrar um ponto de interesse no seu mapa. É uma API RESTful concebida para os programadores procurarem endereços, pontos de interesse e outras informações geográficas. O serviço de Pesquisa atribui informações de latitude e longitude a um endereço especificado. O Módulo de Serviço explicado a seguir pode ser usado para procurar um local usando a API de Pesquisa de Mapas.

Nota

Desativação do Módulo de Serviço SDK da Web do Azure Maps

O Módulo de Serviço SDK da Web do Azure Maps foi preterido e será desativado em 30/09/26. Para evitar interrupções de serviço, recomendamos migrar para o SDK REST JavaScript do Azure Maps até 30/09/26. Para obter mais informações, consulte JavaScript/TypeScript REST SDK Developers Guide (visualização).

Módulo Serviço

No manipulador de eventos de mapa ready , construa a URL do serviço de pesquisa adicionando o seguinte código JavaScript imediatamente após map.layers.add(resultLayer);:
```
//Use MapControlCredential to share authentication between a map control and the service module.
var pipeline = atlas.service.MapsURL.newPipeline(new atlas.service.MapControlCredential(map));

// Construct the SearchURL object
var searchURL = new atlas.service.SearchURL(pipeline); 
```
- Use MapControlCredential para compartilhar a autenticação entre um controle de mapa e o módulo de serviço ao criar um novo objeto de pipeline .
- O searchURL representa uma URL para o Azure Maps MapControlCredential.
Em seguida, adicione o seguinte bloco de script logo abaixo do código anterior adicionado no manipulador de eventos do mapa ready . Este é o código para criar a consulta de pesquisa. Ele usa o serviço Fuzzy Search, uma API de pesquisa básica do Serviço de Pesquisa. O serviço de Pesquisa Fuzzy lida com a maioria das entradas difusas, como endereços, locais e pontos de interesse (POI). Este código procura postos de gasolina próximos dentro do raio especificado da latitude e longitude fornecidas. Uma coleção de recursos GeoJSON da resposta é então extraída usando o geojson.getFeatures() método e adicionada à fonte de dados, o que resulta automaticamente nos dados sendo renderizados na camada de símbolos dos mapas. A última parte deste bloco de script define a visualização da câmera de mapas usando a caixa delimitadora dos resultados usando a propriedade setCamera do mapa.
```
var query = 'gasoline-station';
var radius = 9000;
var lat = 47.64452336193245;
var lon = -122.13687658309935;

searchURL.searchPOI(atlas.service.Aborter.timeout(10000), query, {
    limit: 10,
    lat: lat,
    lon: lon,
    radius: radius,
    view: 'Auto'
}).then((results) => {

    // Extract GeoJSON feature collection from the response and add it to the datasource
    var data = results.geojson.getFeatures();
    datasource.add(data);

    // set camera to bounds to<Your Azure Maps Subscription Key> show the results
    map.setCamera({
        bounds: data.bbox,
        zoom: 10,
        padding: 15
    });
});
```
Guarde o ficheiro MapSearch.html e atualize o browser. Você deve ver o mapa centrado em Seattle com pinos azuis redondos para locais de postos de gasolina na área.
Pode ver os dados não processados que o mapa está a compor, introduzindo o seguinte HTTPRequest no seu browser. Substitua <Your Azure Maps Subscription Key> pela sua chave de subscrição.
```
https://atlas.microsoft.com/search/poi/json?api-version=1.0&query=gasoline%20station&subscription-key={Your-Azure-Maps-Subscription-key}&lat=47.6292&lon=-122.2337&radius=100000
```

Neste momento, a página de MapSearch pode apresentar as localizações dos pontos de interesse devolvidos por uma consulta de pesquisa difusa. Vamos adicionar algumas capacidades interativas e mais informações sobre as localizações.

Adicionar dados interativos

O mapa criado até ao momento está focado apenas nos dados de longitude/latitude para os resultados da pesquisa. No entanto, o JSON bruto que o serviço de Pesquisa de Mapas retorna contém informações adicionais sobre cada posto de gasolina. Incluindo o nome e endereço. Pode incorporar esses dados no mapa com caixas de pop-up interativas.

Adicione as seguintes linhas de código no manipulador de eventos de mapa ready após o código para consultar o serviço de pesquisa difusa. Esse código cria uma ocorrência de um Popup e adiciona um evento mouseover à camada de símbolos.
```
// Create a popup but leave it closed so we can update it and display it later.
popup = new atlas.Popup();

//Add a mouse over event to the result layer and display a popup when this event fires.
map.events.add('mouseover', resultLayer, showPopup);
```
A API atlas.Popup fornece uma janela de informações ancorada na posição necessária no mapa.

Adicione as seguintes linhas de código no manipulador de eventos map ready após o código para criar uma instância de um Popup e adicionar um evento mouseover à camada de símbolos. Este código mostra uma janela pop-up com os resultados quando você passa o mouse sobre um ponto de interesse.

function showPopup(e) {
    //Get the properties and coordinates of the first shape that the event occurred on.

    var p = e.shapes[0].getProperties();
    var position = e.shapes[0].getCoordinates();

    //Create HTML from properties of the selected result.
    var html = `
      <div style="padding:5px">
        <div><b>${p.poi.name}</b></div>
        <div>${p.address.freeformAddress}</div>
        <div>${position[1]}, ${position[0]}</div>
      </div>`;

    //Update the content and position of the popup.
    popup.setPopupOptions({
        content: html,
        position: position
    });

    //Open the popup.
    popup.open(map);
}

Guarde o ficheiro e atualize o browser. Agora, o mapa no navegador mostra pop-ups de informações quando você passa o mouse sobre qualquer um dos pinos de pesquisa.

Para obter o código completo usado neste tutorial, consulte o tutorial de pesquisa no GitHub.
Para ver este exemplo em direto, consulte Procurar pontos de interesse no site de Exemplos de Código do Azure Maps.

Próximos passos

O próximo tutorial demonstra como apresentar um percurso entre duas localizações.

Encaminhar para um destino