Usa la API de Places Aggregate para crear una puntuación de ubicación personalizada

Objetivo

Encontrar la ubicación ideal, ya sea un hotel para tus próximas vacaciones o un departamento apto para familias, suele ser un proceso frustrante y que requiere mucho tiempo para comparar numerosas opciones. ¿Qué pasaría si pudieras ayudar a tus usuarios a tomar decisiones más fácilmente proporcionándoles una métrica personalizada que revele la idoneidad de un hotel para los turistas o clasifique los anuncios de apartamentos según su adecuación para familias, y así transformar una tarea tediosa en una decisión sin esfuerzo?

En este documento, se describe cómo usar la API de Places Aggregate para generar puntuaciones de ubicación personalizadas y dinámicas según la densidad de lugares dentro de un área geográfica definida. La puntuación, una clasificación numérica según los criterios especificados, comunicará de inmediato qué tan adecuada es la ubicación para sus necesidades.

Imagina que promocionas hoteles en una ciudad y quieres destacar los que se encuentran en las zonas turísticas más atractivas creando una puntuación de idoneidad para turistas. Usa la API de Places Aggregate para contar cuántos tipos de lugares relevantes hay cerca de cada hotel. Por ejemplo, sabes que tus clientes valoran los hoteles en ubicaciones cercanas a los siguientes lugares:

• Restaurantes y cafeterías
• Parques y museos
• Tiendas de ropa

Si aplicas ponderaciones de importancia a los recuentos de estos tipos de lugares seleccionados, puedes calcular una puntuación general para cada ubicación de hotel. La puntuación refleja la idoneidad general de la ubicación, según los lugares cercanos. Las ponderaciones asignadas a cada tipo de lugar deben alinearse con tu caso de uso específico y con lo que es importante para tu público objetivo. En este documento, se usará una puntuación de bueno para turistas como ejemplo principal, pero tu puntuación se puede crear para reflejar las necesidades y los datos demográficos de tus usuarios.

Requisitos previos

Antes de leer este documento, se recomienda que te familiarices con la siguiente documentación:

• Documentación para desarrolladores de la API de Places Aggregate para comprender los detalles técnicos y los parámetros disponibles
• [Opcional] Documentación para desarrolladores de la API de Gemini Developer para comprender cómo llamar a Gemini con una API. Se usa en este documento como una opción para generar la puntuación de ubicación personalizada.

Demostración

En esta demostración, se muestra un ejemplo de la puntuación de ubicación personalizada en acción. Elige una ciudad en el menú desplegable y haz clic en el botón Calcular la puntuación personalizada para mostrar la puntuación de ubicación personalizada de cinco ubicaciones completadas previamente.

Selecciona los tipos de lugares pertinentes

El primer paso para crear tu Puntuación de ubicación personalizada es decidir qué tipos de lugares son relevantes para tus clientes en la Tabla A. Como estamos creando una puntuación de bueno para turistas, seleccionamos los siguientes tipos de lugares cerca de los que los turistas querrán estar durante su estadía:

• restaurante
• parque
• clothing_store
• museo
• coffee_shop

A continuación, asigna una ponderación a cada uno de estos tipos de lugar, que refleje su importancia relativa en la puntuación final. Las ponderaciones deben determinarse en función de lo que sea más importante para tu caso de uso y las preferencias del usuario. En este ejemplo, la escala de ponderación estará entre 0 y 1, de la siguiente manera:

Llama a la API de Places Aggregate

Ahora que tienes una lista de los tipos de lugares que te interesan, el siguiente paso es llamar a la API de Places Aggregate.

La API de Places Aggregate requiere un filtro de ubicación. Para este ejemplo, usa circle, con el centro latLng como la ubicación de tu hotel y un radius de 500 m. También establece ratingFilter para que devuelva lugares con una calificación entre 3.8 y 5, y excluye de los recuentos los lugares con calificaciones más bajas.

Experimenta con diferentes parámetros de configuración del filtro de ubicación para tu caso de uso específico. Por ejemplo, es posible que desees capturar lugares dentro de un radio más amplio desde tu centro de latitud y longitud aumentando el valor del radio. Como alternativa, puedes usar otro método para establecer el área de búsqueda, como Región o Área personalizada.

Familiarízate con la sección del filtro de ubicación de la documentación de la API de Places Aggregate para conocer las opciones disponibles.

Llama a la API de Places Aggregate para cada tipo de lugar y ubicación para los que desees generar una puntuación personalizada. Por ejemplo, llama al tipo de lugar del restaurante para uno de tus hoteles:

curl --location 'https://areainsights.googleapis.com/v1:computeInsights' \
--header 'X-Goog-Api-Key: API_KEY \
--header 'Content-Type: application/json' \
--data '{
    "insights": [
        "INSIGHT_COUNT"
    ],
    "filter": {
        "locationFilter": {
            "circle": {
                "latLng": {
                    "latitude": 51.51611,
                    "longitude": -0.12726
                },
                "radius": 500
            }
        },
        "typeFilter": {
            "includedTypes": [
                "restaurant"
            ]
        },
        "ratingFilter": {
            "minRating": 3.8,
            "maxRating": 5
        }
    }
}'

Después de completar todas las llamadas a la API, tendrás datos similares a los siguientes para cada ubicación:

Genera la puntuación de ubicación personalizada

Ahora que tienes el recuento de lugares y la ponderación para cada tipo de lugar en cada ubicación, puedes generar la puntuación de ubicación personalizada. En esta sección, analizaremos dos opciones: usar un algoritmo local o la API de Gemini Developer.

Opción 1: Usa un algoritmo

La primera opción que analizaremos es el uso de un algoritmo local para generar una puntuación con las ponderaciones y los recuentos de cada tipo de lugar. Normaliza esta puntuación en una escala de 0 a 5, en la que los valores más altos indican un área más atractiva según tus criterios. Para este ejemplo, genera dos objetos JavaScript a partir de los datos anteriores:

    {
      "restaurant": 56,
      "park": 3,
      "clothing_store": 32,
      "museum": 8,
      "coffee_shop": 41
    }
    

    {
      "restaurant": 0.8,
      "park": 0.6,
      "clothing_store": 0.3,
      "museum": 0.2,
      "coffee_shop": 0.5
    }
    

Para generar una puntuación a partir de los recuentos y las ponderaciones, multiplica el itemCounts por el typeWeights y suma los resultados a un weightedCount general:

let weightedCount = 0;
for (const itemType in itemCounts) {
  weightedCount += itemCounts[itemType] * typeWeights[itemType];
}
weightedCount = weightedCount.toFixed(2);

En este ejemplo, el resultado de este paso es 78.3.

Ahora puedes usar la normalización logarítmica para generar la puntuación final de esta ubicación en una escala del 0 al 5:

if (weightedCount === 0) {
   normalizedScore = 0;
} else {
   normalizedScore = Math.log(weightedCount + 1);
}

// Clamp between 0 and 5
normalizedScore = Math.max(0, Math.min(5, normalizedScore));

En este ejemplo, el resultado de la puntuación final es 4.36 (redondeado a dos decimales).

Opción 2: Usa la API de Gemini Developer

Como alternativa a usar un algoritmo local, la API de Gemini Developer ofrece una forma eficaz de calcular la puntuación de ubicación personalizada para todas las ubicaciones. Solo tienes que proporcionar los datos de recuento y ponderación con las instrucciones del sistema para todas las ubicaciones de tus hoteles.

Este método es especialmente útil si tienes información detallada que te gustaría incluir en el cálculo, como la siguiente:

• Son las descripciones de texto de cada ubicación del hotel, por ejemplo: "Esta ubicación es adecuada para familias y el área es tranquila por la noche".
• Información sobre tu usuario, como: "Este usuario está reservando para una familia y prefiere un área tranquila en una ubicación central".

La API para desarrolladores de Gemini puede comprender y tener en cuenta estos datos cualitativos, lo que genera una puntuación más sofisticada y pertinente que un enfoque puramente matemático.

Si usas la API de Gemini para desarrolladores, además de la tabla de ponderación y el tipo de lugar que se muestran arriba, puedes tener datos de descripción para cada ubicación, como los siguientes:

Estas descripciones cualitativas, junto con cualquier información o preferencia del usuario, se pueden incluir en tu instrucción a Gemini.

Instrucciones del sistema

Gemini requiere instrucciones, junto con los datos sin procesar, para saber que se espera que genere una puntuación para cada ubicación, según los datos proporcionados. Una instrucción del sistema de ejemplo para lograr esto podría ser la siguiente:

You will be given a json file containing details about a number of locations grouped by their latitude and longitudes.

Within the location details is information about the count of places nearby the location that match a specific category, and the weighting of importance of that category, between 0 - 1.

You will also be given information about the user's preference, and a description of each location. Take this into consideration when generating scores.

Generate a location suitability score taking these into account for each location. The score should be between 1 - 5 inclusive, to two decimal places. The minimum score a location can receive is 1.

Output in JSON

Las instrucciones del sistema anteriores le permiten a Gemini saber qué datos esperar y cuál es el resultado esperado del modelo de IA. También solicita el resultado en formato JSON.

Resultados estructurados

Si bien le pedimos a Gemini que genere el resultado en formato JSON, debemos ser más específicos sobre la estructura del resultado para saber qué esperar cuando le hagamos consultas con código. Para ello, podemos agregar una instrucción adicional de salida estructurada a la solicitud, usando el campo responseSchema en la API de Gemini. Esto usa un objeto de esquema de OpenAPI para restringir el resultado del modelo.

Por ejemplo:

{
  "type": "array",
  "description": "Array of location data with score",
  "items": {
    "type": "object",
    "properties": {
      "location": {
        "type": "object",
        "description": "Geographical coordinates of the location",
        "properties": {
          "latitude": {
            "type": "number",
            "format": "float",
            "description": "Latitude of the location"
          },
          "longitude": {
            "type": "number",
            "format": "float",
            "description": "Longitude of the location"
          }
        },
        "required": [
          "latitude",
          "longitude"
        ]
      },
      "score": {
        "type": "string",
        "description": "A score associated with the location"
      }
    },
    "required": [
      "location",
      "score"
    ]
  }
}

En este ejemplo, se solicita que Gemini genere un array de JavaScript con lo siguiente:

• Latitud y longitud de la ubicación
• La puntuación de ubicación personalizada

Con las instrucciones del sistema y el resultado estructurado anteriores, la respuesta de Gemini para una ubicación se vería de la siguiente manera, con score como la puntuación de ubicación personalizada:

[
  {
    "location": {
      "latitude": 51.51611,
      "longitude": -0.12726
    },
    "score": "4.13"
  }
]

Cómo mostrar la puntuación

Una vez que hayas generado la puntuación de la ubicación personalizada para cada ubicación con uno de los métodos descritos, se podrá mostrar junto con los detalles de tu hotel o usarse como una opción de filtro de búsqueda. Por ejemplo, "Muéstrame lugares con una puntuación alta de bueno para turistas". Esto permitirá que tus clientes tomen decisiones basadas en datos cuando realicen reservas.

Conclusión

Usar las puntuaciones de ubicación personalizadas puede ser una herramienta eficaz para brindarles a los usuarios una descripción general de la idoneidad de un área. En este documento, se demostró cómo generar puntuaciones de ubicación personalizadas para varias ubicaciones usando cinco tipos de lugares separados. Esta implementación se puede modificar para que se adapte a tus necesidades, y los tipos de lugares similares se pueden combinar en una sola solicitud para devolver el recuento agregado de esos tipos y proporcionarlo a tu solución personalizada de puntuación de ubicación.

Prueba la API de Places Aggregate hoy mismo para generar puntuaciones de ubicación útiles que ayuden a tus clientes a tomar decisiones fundamentadas basadas en la ubicación.

Colaboradores

Henrik Valve | Ingeniero de DevX