Puntuaciones de ubicación personalizadas de Places Aggregate

Objetivo

Encontrar la ubicación ideal, ya sea un hotel para tus próximas vacaciones o un departamento apto para familias, suele implicar un proceso frustrante y lento en el que se comparan numerosas opciones. ¿Qué pasaría si pudieras ayudar a que esto sea más fácil para tus usuarios proporcionando una métrica personalizada que revele la idoneidad de un hotel para los turistas o clasifique los anuncios de departamentos según su idoneidad para familias, transformando 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 dinámicas y personalizadas según la densidad de lugares dentro de un área geográfica definida. La puntuación, una clasificación numérica en función de los criterios que especificaste, comunicará al instante qué tan adecuada es la ubicación para sus necesidades.

Imagina una situación en la 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 que se encuentran cerca de varios de 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 puedes crear tu puntuación para reflejar los datos demográficos y las necesidades 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 y se usa en este documento como una opción para generar la puntuación de ubicación personalizada.

Selecciona los tipos de lugares relevantes

El primer paso para crear tu puntuación de ubicación personalizada es decidir qué tipos de lugares de la tabla A son relevantes para tus clientes. 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 lugares, lo que refleja su importancia relativa en la puntuación final. Las ponderaciones se deben determinar en función de lo que sea más importante para tu caso de uso y las preferencias de tus usuarios. 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 el ratingFilter para que se devuelvan lugares con una calificación entre 3.8 y 5, lo que excluye los lugares con calificaciones más bajas de los recuentos.

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

Familiarízate con la sección de filtros 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 quieras generar una puntuación personalizada. Por ejemplo, llama al tipo de lugar de 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 que se completen todas las llamadas a la API, tendrás datos como 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 de cada tipo de lugar para 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 abordaremos es usar 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 de 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
    }
    

Genera una puntuación a partir de los recuentos y las ponderaciones multiplicando el itemCounts por el typeWeights y sumando 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 entre 0 y 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 al uso de un algoritmo local, la API de Gemini Developer ofrece una forma potente de calcular la puntuación de ubicación personalizada para todas las ubicaciones. Solo debes proporcionar los datos de recuento y ponderación con 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:

• Descripciones de texto para 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 de Gemini Developer puede comprender y tener en cuenta estos datos cualitativos, lo que genera una puntuación más sofisticada y pertinente que va más allá de un enfoque puramente matemático.

Si usas la API de Gemini Developer, además del tipo de lugar y la tabla de ponderación anteriores, puedes tener datos de descripción para cada ubicación que se vean de la siguiente manera:

Estas descripciones cualitativas, junto con cualquier información o preferencia del usuario, se pueden incluir en tu instrucción para 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. Un ejemplo de instrucción del sistema para lograrlo podría ser el 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 JSON.

Resultados estructurados

Si bien le pedimos a Gemini que genere el resultado en JSON, debemos ser más específicos sobre la estructura del resultado para saber qué esperar cuando lo consultemos con código. Para ello, podemos agregar una instrucción de salida estructurada adicional a la solicitud con 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, donde score es la puntuación de ubicación personalizada:

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

Muestra la puntuación

Una vez que hayas generado la puntuación de ubicación personalizada para cada ubicación con uno de los métodos descritos, se puede mostrar junto con los detalles de tu hotel o usarse como una opción de filtrado 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 reserven.

Conclusión

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

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

Colaboradores

Henrik Valve | Ingeniero de DevX