Tutorial: Búsqueda de puntos cercanos de interés mediante Azure Maps

Artículo
04/09/2024

En este tutorial se muestra cómo configurar una cuenta con Azure Maps y luego usar las API de Maps para buscar un punto de interés. En este tutorial, aprenderá a:

Crear una cuenta de Azure Maps
Recuperar la clave de suscripción de la cuenta de Maps
Crear una nueva página web con Map Control API
Usar el servicio de búsqueda de Maps para encontrar un punto cercano de interés

Requisitos previos

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

Una cuenta de Azure Maps
Una clave de suscripción

Nota

Para más información sobre la autenticación en Azure Maps, consulte Administración de la autenticación en Azure Maps.

Creación de un nuevo mapa

La API de Control de mapa es una práctica biblioteca cliente. Esta API permite integrar fácilmente Azure Maps en la aplicación web. Oculta la complejidad de las llamadas sin servicio de REST e impulsa la productividad con componentes que se pueden personalizar. En los pasos siguientes se muestra cómo crear una página HTML estática insertada con Map Control API.

En el equipo local, cree un nuevo archivo y asígnele el nombre MapSearch.html.

Agregue los siguientes componentes HTML al archivo:

 <!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>

Algunos aspectos que debe saber con respecto al código HTML anterior:

El encabezado HTML incluye los archivos de recursos CSS y JavaScript hospedados por la biblioteca de Control de mapa de Azure.
El evento onload en el cuerpo de la página llama a la función GetMap cuando el cuerpo de la página se haya cargado.
La función GetMap contiene el código JavaScript insertado que se usa para acceder a las API de Azure Maps. Se agrega en el paso siguiente.

Agregue el siguiente código JavaScript a la función GetMap del archivo HTML. Reemplace la cadena <Your Azure Maps Subscription Key> por la clave de suscripción que ha copiado de la cuenta de 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>'
    }
});
```
Algunos aspectos que debe saber con respecto al código JavaScript anterior:
- El núcleo de la función GetMap, que inicializa la API de Control de mapa para la clave de cuenta de Azure Maps.
- atlas es el espacio de nombres que contiene la API y los componentes visuales relacionados.
- atlas.Map proporciona el control para un mapa web visual e interactivo.
Guarde los cambios en el archivo y abra la página HTML en un explorador. El mapa mostrado es el más básico que puede crear con una llamada a atlas.Map mediante la clave de cuenta.
En la función GetMap, después de inicializar el mapa, agregue el siguiente 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);
});
```
Información sobre este código:
- Se agrega un evento ready al mapa, que se desencadena cuando los recursos del mapa terminan de cargarse y ya se puede acceder al mapa.
- En el controlador de eventos ready del mapa, se crea un origen de datos para almacenar datos de resultados.
- Se crea una capa de símbolos y se asocia al origen de datos. Esta capa especifica cómo se deben representar los datos de los resultados en el origen de datos. En este caso, el resultado se representa con un icono de chincheta redonda de color azul oscuro, centrado sobre la coordenada de resultados, que permite que otros iconos se superpongan.
- La capa resultante se agrega a las capas de mapa.

Adición de funcionalidades de búsqueda

En esta sección se muestra cómo usar Search API de Maps para buscar un punto de interés en el mapa. Se trata de una API RESTful diseñada para los desarrolladores para buscar direcciones, puntos de interés y otra información geográfica. El servicio Search asigna información de latitud y longitud a una dirección especificada. El módulo de servicio que se explica a continuación puede usarse para buscar una ubicación mediante la API de búsqueda de Maps.

Nota:

Retirada del módulo de servicio del SDK de Azure Maps para web

El módulo de servicio del SDK de Azure Maps para web ya está en desuso y se retirará el 30 de septiembre de 2026. Para evitar interrupciones del servicio, se recomienda migrar al SDK de Azure Maps para REST de JavaScript antes del 30 de septiembre de 2026. Para obtener más información, consulte la Guía para desarrolladores del SDK de REST de JavaScript/TypeScript.

Módulo de servicio

En el controlador de eventos ready del mapa, construya la dirección URL del servicio de búsqueda; para ello, agregue el siguiente código JavaScript inmediatamente después de 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 el objeto MapControlCredential para compartir la autenticación entre un control de mapa y el módulo de servicio al crear un nuevo objeto pipeline.
- searchURL representa una dirección URL para MapControlCredential de Azure Maps.
A continuación, agregue el siguiente bloque de script justo debajo del código anterior que acaba de agregar en el controlador de eventos ready del mapa. Este es el código para compilar la consulta de búsqueda. Este fragmento de código usa el servicio Fuzzy Search, que es una API de búsqueda básica del servicio Search. El servicio Fuzzy Search controla la mayoría de las entradas aproximadas como, por ejemplo, direcciones, lugares y puntos de interés (POI). Este código busca las gasolineras más cercanas en el radio especificado de las coordenadas de latitud y longitud proporcionadas. Después, se extrae una colección de características GeoJSON de la respuesta con el método geojson.getFeatures() y se agregan al origen de datos, lo cual provoca que los datos se representen automáticamente en la capa de símbolos del mapa. La última parte de este bloque de script permite establecer la vista de cámaras del mapa mediante el rectángulo delimitador de los resultados con la propiedad setCamera del 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 el archivo MapSearch.html y actualice el explorador. El mapa se centrará en Seattle y aparecerán marcadas con chinchetas azules redondas las ubicaciones de las gasolineras de la zona.
Puede ver los datos sin procesar que está representando el mapa especificando la siguiente solicitud HTTPRequest en el explorador. Reemplace <Your Azure Maps Subscription Key> por la clave de suscripción.
```
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
```

En este momento, la página MapSearch puede mostrar las ubicaciones de los puntos de interés que se devuelven en una consulta de búsqueda aproximada. Vamos a agregar algunas funcionalidades interactivas y más información sobre las ubicaciones.

Adición de datos interactivos

La asignación que hemos hecho hasta ahora solo examina los datos de latitud o longitud de los resultados de búsqueda. No obstante, el JSON sin formato que devuelve el servicio de búsqueda de Azure Maps contiene información adicional sobre cada gasolinera, como el nombre y la dirección. Puede incorporar esos datos al mapa con cuadros emergentes interactivos.

Agregue las siguientes líneas de código en el controlador de eventos ready del mapa después del código para consultar el servicio de búsquedas aproximadas. Este código crea una instancia de un elemento emergente y agrega un evento mouseover a la capa 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);
```
La API atlas.Popup proporciona una ventana de información anclada en la posición requerida en el mapa.

Agregue las siguientes líneas de código en el controlador de eventos ready del mapa después del código para crear una instancia de un elemento emergente y agregar un evento mouseover a la capa de símbolos. Este código muestra una ventana emergente con los resultados al pasar el mouse sobre un punto de interés.

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 el archivo y actualice el explorador. Ahora el mapa del explorador muestra los elementos de información emergentes cuando se mantiene el mouse sobre cualquiera de los marcadores de búsqueda.

Para obtener el código completo que se usa en este tutorial, consulte el tutorial de búsqueda en GitHub.
Para ver este ejemplo en directo, consulte Búsqueda de puntos de interés en el sitio Ejemplos de código de Azure Maps.

Pasos siguientes

En el siguiente tutorial se muestra cómo visualizar una ruta entre dos ubicaciones.

Ruta a un destino