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, a menudo implica un proceso frustrante y lento de comparar varias opciones. ¿Qué tal si pudieras ayudar a facilitarles esto a los usuarios proporcionando una métrica personalizada que revele la idoneidad de un hotel para los turistas o que clasifique las fichas de los departamentos en función de su idoneidad para familias, lo que transformaría una tarea tediosa en una decisión sencilla?

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á 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 áreas turísticas más atractivas creando una calificación de buen lugar 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 que están cerca 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 buena para los turistas como ejemplo principal, pero tu puntuación se puede crear para reflejar los datos demográficos y las necesidades de tus usuarios.

Requisitos previos

Antes de leer este documento, te recomendamos que estés familiarizado 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 que 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 del menú desplegable y haz clic en el botón Calcular puntuación personalizada para mostrar la puntuación de ubicación personalizada de cinco ubicaciones prepropagadas.

Selecciona los tipos de lugares relevantes

El primer paso para crear tu puntuación de ubicación personalizada es decidir los tipos de lugares que son relevantes para tus clientes en la Tabla A. Como estamos creando una puntuación de Buena para turistas, seleccionamos los siguientes tipos de lugares que los turistas querrán visitar 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 deben determinarse en función de lo que es 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. En este ejemplo, usa circle, con el latLng central como la ubicación de tu hotel y un radius de 500 m. También establece ratingFilter para que muestre lugares con una calificación entre 3.8 y 5, y excluye los lugares con calificaciones más bajas de los recuentos.

Experimenta con la variación de la configuración del filtro de ubicación para tu caso de uso específico. Por ejemplo, si deseas capturar lugares dentro de un radio más amplio desde tu latitud y longitud centrales, aumenta el valor del radio. 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 del filtro de ubicación de la documentación de la API de Places Aggregate para obtener información sobre las opciones disponibles.

Llama a la API de Places Aggregate para cada tipo de lugar y ubicación para la que desees generar una puntuación personalizada. Por ejemplo, llama al tipo de lugar de restaurante de 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 que se ven así 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 de 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 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. En 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 ponderaciones, multiplica itemCounts por 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 de 0 a 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 final de la puntuación 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 las instrucciones del sistema para todas las ubicaciones de tu hotel.

Este método es especialmente útil si tienes información detallada que deseas 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 reserva para una familia y prefiere un área tranquila en una ubicación céntrica".

La API de Gemini Developer puede comprender y tener en cuenta estos datos cualitativos, lo que genera una puntuación más sofisticada y relevante 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 que se muestra arriba, puedes tener datos de descripción para cada ubicación que se vea 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 lograr esto 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 con la estructura del resultado para saber qué esperar cuando lo consultemos con código. Para ello, podemos agregar una instrucción adicional de salida estructurada a la solicitud, con el campo responseSchema de la API de Gemini. Para ello, se 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 la 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, en la que score es 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 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 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 hagan reservas.

Conclusión

El uso de puntuaciones de ubicaciones personalizadas puede ser una herramienta eficaz para brindar a los usuarios una descripción general rápida de la idoneidad de un área. En este documento, se muestra cómo generar puntuaciones de ubicación personalizadas para varias ubicaciones con cinco tipos de lugares separados. Esta implementación se puede modificar para satisfacer tus necesidades, y los tipos de lugares similares se pueden combinar en una solicitud para mostrar el recuento agregado de esos tipos y proporcionarlo a tu solución de puntuación de ubicación personalizada.

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

Colaboradores

Henrik Valve | Ingeniero de DevX