Búsqueda de ubicaciones con los servicios Search de Azure Maps

  • Artículo

El servicio Search es un conjunto de API de RESTful diseñadas para que los desarrolladores busquen direcciones, lugares y listados de empresas por nombre, categoría u otra información geográfica. Además de permitir la geocodificación tradicional, los servicios pueden realizar también la geocodificación inversa de direcciones y calles transversales en función de la longitud y la latitud. Los valores de latitud y longitud devueltos por la búsqueda se pueden usar como parámetros en otros servicios de Azure Maps, como los de ruta y tiempo.

En este artículo se explica cómo:

  • Solicitar las coordenadas de latitud y longitud de una dirección (geocodificación de la ubicación de la dirección) mediante Búsqueda de dirección.
  • Buscar una dirección o punto de interés (POI) mediante Búsqueda aproximada.
  • Realizar una búsqueda de dirección inversa para traducir la ubicación de coordenadas a la dirección postal.
  • Traduce la ubicación de las coordenadas a un cruce de calles comprensible para los humanos mediante Buscar dirección de cruce inverso, que se necesita con mayor frecuencia en las aplicaciones de seguimiento que reciben una señal de GPS de un dispositivo o activo y desean saber dónde se encuentra la coordenada.

Prerrequisitos

En este tutorial se usa la aplicación Postman, pero puede elegir un entorno de desarrollo de API diferente.

Solicitud de la latitud y longitud de una dirección (geocodificación)

El ejemplo de esta sección utiliza Obtener dirección de búsqueda para convertir una dirección en coordenadas de latitud y longitud. Este proceso también se denomina geocodificación. Además de devolver las coordenadas, la respuesta también devuelve propiedades detalladas de la dirección, como información sobre la calle, el código postal, el municipio y el país o la región.

Sugerencia

Si tiene un conjunto de direcciones para realizar la geocodificación, puede usar la Búsqueda de direcciones por lotes para enviar un lote de consultas en una única llamada solicitud.

  1. En la aplicación Postman, seleccione Nuevo para crear la solicitud. En la ventana Crear nuevo, seleccione Solicitud HTTP. Escriba un valor de Request name (Nombre de solicitud) para la solicitud.

  2. Seleccione el método GET HTTP en la pestaña del generador y escriba la dirección URL siguiente. En esta solicitud, estamos buscando una dirección específica: 400 Braod St, Seattle, WA 98109. Para esta solicitud y otras solicitudes mencionadas en este artículo, reemplace {Your-Azure-Maps-Subscription-key} por su clave de suscripción de Azure Maps.

    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. Seleccione el botón azul Enviar. El cuerpo de la respuesta contiene datos para una sola ubicación.

  4. A continuación, busca una dirección que tenga más de una ubicación posible. En la sección Params (Parámetros), cambie la clave query a 400 Broad, Seattle. Seleccione el botón azul Enviar.

    Search for address

  5. Luego, intente establecer la clave query en 400 Broa.

  6. Seleccione el botón Enviar. La respuesta incluye resultados de varios países y regiones. Para sesgar geográficamente los resultados al área pertinente para el usuario, agregue siempre a la solicitud tantos detalles como sea posible.

Búsqueda aproximada admite búsquedas estándar de una sola línea y de forma libre. Se recomienda usar Azure Maps Search Fuzzy API de Azure Maps cuando no conozca el tipo de entrada del usuario de una solicitud de búsqueda. La entrada de la consulta puede ser una dirección completa o parcial. También puede ser un token de punto de interés (POI), como un nombre de POI, una categoría de POI o el nombre de una marca. Además, para mejorar la relevancia de los resultados de la búsqueda, restringe los resultados de la consulta utilizando una ubicación de coordenadas y un radio o definiendo un cuadro de límite.

Sugerencia

La mayoría de las consultas de búsqueda tienen como valor predeterminado maxFuzzyLevel=1 para mejorar el rendimiento y reducir los resultados inusuales. Ajusta los niveles de aproximación usando los parámetros maxFuzzyLevel o minFuzzyLevel. Para obtener más información sobre maxFuzzyLevel y una lista completa de todos los parámetros adicionales, consulte Parámetros de identificador URI de Búsqueda aproximada.

En el ejemplo de esta sección, se usa Fuzzy Search para buscar pizza en todo el mundo y, después, se busca en el ámbito de un país y región específico. Finalmente, demuestra cómo usar una ubicación de coordenadas y un radio para realizar una búsqueda en un área específica y limitar la cantidad de resultados devueltos.

Importante

Para sesgar geográficamente los resultados al área pertinente para los usuarios, agregue siempre tantos detalles de ubicación como sea posible. Para obtener más información, consulta los Procedimientos recomendados para la búsqueda.

  1. En la aplicación Postman, seleccione Nuevo para crear la solicitud. En la ventana Crear nuevo, seleccione Solicitud HTTP. Escriba un valor de Request name (Nombre de solicitud) para la solicitud.

  2. Seleccione el método GET HTTP en la pestaña del generador y escriba la dirección URL siguiente. Para esta solicitud y otras solicitudes mencionadas en este artículo, reemplace {Your-Azure-Maps-Subscription-key} por su clave de suscripción de Azure Maps.

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

    Nota

    El atributo json de la ruta de acceso URL determina el formato de respuesta. En este artículo se usa JSON para facilitar el uso y la legibilidad. Para buscar otros formatos de respuesta admitidos, consulte la definición del parámetro format en la documentación de referencia Parámetros de identificador URI.

  3. Haz clic en Enviar y revisa el cuerpo de la respuesta.

    La cadena de consulta ambigua para "pizza" devolvió 10 resultados de punto de interés (POI) en las categorías "pizza" y "restaurante". Cada resultado incluye detalles como una dirección, valores de latitud y longitud, ventanilla y puntos de entrada para la ubicación. Los resultados ahora son variados para esta consulta y no están asociados a ninguna ubicación de referencia.

    En el paso siguiente, usarás el parámetro countrySet para especificar solo los países o regiones para los que la aplicación necesita cobertura. Para una lista completa de los países y regiones admitidos, consulte Cobertura de búsqueda.

  4. El comportamiento predeterminado es buscar en todo el mundo, lo que puede devolver resultados innecesarios. A continuación, busca pizza solo en los Estados Unidos. Agregue la clave countrySet a la sección Params (Parámetros) y establezca su valor en US. Al establecer la clave countrySet en US, limita los resultados a los Estados Unidos.

    Search for pizza in the United States

    Ahora los resultados están limitados por el código de país y la consulta devuelve pizzerías de los Estados Unidos.

  5. Para obtener una búsqueda aún más específica, puede buscar en el alcance de un par de coordenadas de latitud/longitud. El siguiente ejemplo utiliza las coordenadas de latitud y longitud de la Aguja Espacial de Seattle. Como solo queremos que se devuelvan resultados dentro de un radio de 400 metros, agregamos el parámetro radius. Además, agregamos el parámetro limit para limitar los resultados a las cinco pizzerías más cercanas.

    En la sección Params (Parámetros), agregue los pares clave-valor siguientes:

    Clave Value
    lat 47,620525
    lon -122,349274
    radio 400
    limit 5

  6. Seleccione Enviar. La respuesta incluye los resultados de restaurantes de pizza cerca de la Space Needle de Seattle.

Búsqueda de dirección inversa traduce las coordenadas en direcciones legibles para cualquier persona. Esta API se usa a menudo para las aplicaciones que consumen fuentes GPS y desean detectar direcciones en puntos de coordenadas específicos.

Importante

Para sesgar geográficamente los resultados al área pertinente para los usuarios, agregue siempre tantos detalles de ubicación como sea posible. Para obtener más información, consulta los Procedimientos recomendados para la búsqueda.

Sugerencia

Si tiene un conjunto de direcciones en forma de coordenadas para realizar la geocodificación inversa, puede usar Búsqueda de dirección inversa por lotes para enviar un lote de consultas en una única solicitud.

Este ejemplo demuestra cómo realizar búsquedas inversas utilizando algunos de los parámetros opcionales que están disponibles. Para una lista completa de los parámetros opcionales, consulte la sección sobre parámetros de búsqueda inversa.

  1. En la aplicación Postman, seleccione Nuevo para crear la solicitud. En la ventana Crear nuevo, seleccione Solicitud HTTP. Escriba un valor de Request name (Nombre de solicitud) para la solicitud.

  2. Seleccione el método GET HTTP en la pestaña del generador y escriba la dirección URL siguiente. Para esta solicitud y otras solicitudes mencionadas en este artículo, reemplace {Your-Azure-Maps-Subscription-key} por su clave de suscripción de Azure Maps. La solicitud debe tener un aspecto similar a la siguiente dirección 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. Selecciona Enviar y revisa el cuerpo de la respuesta. Debería ver un resultado de la consulta. La respuesta incluye información de dirección clave sobre Safeco Field.

  4. A continuación, agrega los siguientes pares clave/valor a la sección Parámetros:

    Clave Value Devuelve
    number 1 La respuesta puede incluir el lado de la calle (izquierda/derecha) y también una posición de desplazamiento para el número.
    returnSpeedLimit true Devuelve el límite de velocidad en la dirección.
    returnRoadUse true Devuelve los tipos de uso de carretera en la dirección. Para ver todos los tipos de uso de carretera posibles, consulte la sección Tipos de uso de carretera.
    returnMatchType true Devuelve el tipo de coincidencia. Para ver todos los valores posibles, consulte Resultados de Búsqueda de dirección inversa.

    Search reverse.

  5. Selecciona Enviar y revisa el cuerpo de la respuesta.

  6. A continuación, agregamos la clave entityType y estableceremos su valor en Municipality. La clave entityType reemplaza a la clave returnMatchType del paso anterior. También es necesario quitar returnSpeedLimit y returnRoadUse, ya que estás solicitando información sobre el municipio. Para ver todos los tipos de entidad posibles, consulte Tipos de entidad.

    Search reverse entityType.

  7. Seleccione Enviar. Compare los resultados con los resultados devueltos en el paso 5. Como el tipo de entidad que se solicita ahora es municipality, la respuesta no incluye información de dirección postal. Además, el valor de geometryId devuelto se puede usar para solicitar un límite poligonal a través de Get Search Polygon API de Azure Maps.

Sugerencia

Para obtener más información sobre estos, así como otros parámetros, consulta Parámetros de búsqueda inversa.

Este ejemplo demuestra cómo buscar un cruce de calles en función de las coordenadas de una dirección.

  1. En la aplicación Postman, seleccione Nuevo para crear la solicitud. En la ventana Crear nuevo, seleccione Solicitud HTTP. Escriba un valor de Request name (Nombre de solicitud) para la solicitud.

  2. Seleccione el método GET HTTP en la pestaña del generador y escriba la dirección URL siguiente. Para esta solicitud y otras solicitudes mencionadas en este artículo, reemplace {Your-Azure-Maps-Subscription-key} por su clave de suscripción de Azure Maps. La solicitud debe tener un aspecto similar a la siguiente dirección 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. Selecciona Enviar y revisa el cuerpo de la respuesta. Observa que la respuesta contiene un valor crossStreet de South Atlantic Street.

Pasos siguientes

Servicio Search de Azure Maps

Procedimientos recomendados del servicio Search de Azure Maps