Utiliser l'API Places Aggregate pour créer un score de lieu personnalisé

Objectif

Trouver l'hébergement idéal, qu'il s'agisse d'un hôtel pour vos prochaines vacances ou d'un appartement adapté aux familles, implique souvent un processus frustrant et long de comparaison de nombreuses options. Que diriez-vous de faciliter la tâche à vos utilisateurs en leur fournissant une métrique personnalisée qui révèle l'adéquation d'un hôtel aux touristes ou classe les annonces d'appartements en fonction de leur caractère adapté aux familles ? Vous transformeriez une tâche fastidieuse en décision facile.

Ce document explique comment utiliser l'API Places Aggregate pour générer des scores de localisation dynamiques et personnalisés en fonction de la densité des lieux dans une zone géographique définie. Le score, qui correspond à un classement numérique en fonction des critères que vous avez spécifiés, indique instantanément dans quelle mesure l'emplacement est adapté à ses besoins.

Imaginons que vous promouvez des hôtels dans une ville et que vous souhaitiez mettre en avant ceux situés dans les zones touristiques les plus attrayantes en créant un score "Bon pour les touristes". Utilisez l'API Places Aggregate pour compter le nombre de types d'établissements pertinents à proximité de chaque hôtel. Par exemple, vous savez que vos clients apprécient les hôtels situés à proximité de certains des éléments suivants:

• Restaurants et cafés
• Parcs et musées
• Magasins de vêtements

En appliquant des pondérations d'importance aux nombres de ces types de lieux sélectionnés, vous pouvez calculer un score global pour chaque hôtel. Ce score reflète l'adéquation globale de l'emplacement, en fonction des lieux à proximité. Les pondérations attribuées à chaque type de lieu doivent correspondre à votre cas d'utilisation spécifique et à ce qui est important pour votre audience cible. Ce document utilise un score adapté aux touristes comme exemple principal, mais vous pouvez créer votre propre score pour refléter les données démographiques et les besoins de vos utilisateurs.

Prérequis

Avant de lire ce document, nous vous recommandons de connaître la documentation suivante:

• Consultez la documentation du développeur sur l'API Places Aggregate pour en savoir plus sur les détails techniques et les paramètres disponibles.
• [Facultatif] Documentation du développeur de l'API Gemini pour comprendre comment appeler Gemini à l'aide d'une API. Elle est utilisée dans ce document comme option pour générer le score de lieu personnalisé.

Démo

Cette démonstration montre un exemple du score de lieu personnalisé en action. Choisissez une ville dans le menu déroulant, puis cliquez sur le bouton Calculer le score personnalisé pour afficher le score personnalisé de cinq emplacements préremplis.

Sélectionner les types de lieux concernés

La première étape de la création de votre score de lieu personnalisé consiste à choisir les types de lieux pertinents pour vos clients dans la tableau A. Comme nous créons un score Bon pour les touristes, nous avons sélectionné les types d'établissements suivants que les touristes voudront fréquenter pendant leur séjour:

• dans un restaurant,
• parc
• clothing_store
• musée
• coffee_shop

Ensuite, attribuez un poids à chacun de ces types de lieux, en fonction de leur importance relative dans le score final. Les pondérations doivent être déterminées en fonction de ce qui est le plus important pour votre cas d'utilisation et les préférences de vos utilisateurs. Pour cet exemple, l'échelle de pondération sera comprise entre 0 et 1, comme suit:

Appeler l'API Places Aggregate

Maintenant que vous disposez d'une liste des types d'établissements qui vous intéressent, l'étape suivante consiste à appeler l'API Places Aggregate.

L'API Places Aggregate nécessite un filtre de zone géographique. Pour cet exemple, utilisez circle, le centre latLng correspondant à l'emplacement de votre hôtel et une radius de 500 m. Définissez également ratingFilter pour afficher les établissements dont la note est comprise entre 3,8 et 5, en excluant les établissements dont la note est inférieure.

Essayez de modifier les paramètres du filtre de zone géographique en fonction de votre cas d'utilisation spécifique. Par exemple, vous pouvez capturer des lieux dans un rayon plus large à partir de la latitude et de la longitude du centre en augmentant la valeur du rayon. Vous pouvez également utiliser une autre méthode pour définir la zone de recherche, comme Région ou Zone personnalisée.

Familiarisez-vous avec la section sur le filtre de lieu de la documentation de l'API Places Aggregate pour découvrir les options disponibles.

Appelez l'API Places Aggregate pour chaque type de lieu et chaque emplacement pour lesquels vous souhaitez générer un score personnalisé. Par exemple, demandez le type de lieu "restaurant" pour l'un de vos hôtels:

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
        }
    }
}'

Une fois tous les appels à l'API effectués, vous disposez de données qui se présentent comme suit pour chaque établissement:

Générer le score personnalisé de l'emplacement

Vous disposez maintenant du nombre de lieux et de la pondération pour chaque type de lieu pour chaque emplacement. Vous pouvez maintenant générer le score d'emplacement personnalisé. Dans cette section, nous allons examiner deux options : utiliser un algorithme local ou l'API Gemini Developer.

Option 1: Utiliser un algorithme

La première option que nous allons aborder consiste à utiliser un algorithme local pour générer un score à l'aide des pondérations et des totaux pour chaque type d'établissement. Normalisez ce score sur une échelle de 0 à 5, où les valeurs plus élevées indiquent une zone plus attrayante en fonction de vos critères. Pour cet exemple, générez deux objets JavaScript à partir des données ci-dessus:

    {
      "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
    }
    

Générez un score à partir des nombres et des pondérations en multipliant itemCounts par typeWeights, puis en ajoutant les résultats à un weightedCount global:

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

Dans cet exemple, le résultat de cette étape est: 78,3.

Vous pouvez maintenant utiliser la normalisation logarithmique pour générer le score final de cet emplacement sur une échelle de 0 à 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));

Pour cet exemple, le score final est: 4,36 (arrondi à deux décimales).

Option 2: Utiliser l'API Gemini Developer

Au lieu d'utiliser un algorithme local, l'API Gemini Developer offre un moyen efficace de calculer le score de lieu personnalisé pour tous les lieux. Il vous suffit de fournir les données de comptage et de pondération avec des instructions système pour tous vos hôtels.

Cette méthode est particulièrement utile si vous souhaitez inclure des informations nuancées dans le calcul, par exemple:

• Descriptions textuelles pour chaque hôtel, par exemple: "Cet hôtel est adapté aux familles et le quartier est calme la nuit".
• Informations sur votre utilisateur, par exemple: "Cet utilisateur réserve pour une famille et préfère un quartier calme dans un emplacement central".

L'API Gemini Developer peut comprendre et prendre en compte ces données qualitatives, ce qui permet d'obtenir un score plus sophistiqué et pertinent que les approches purement mathématiques.

En utilisant l'API Gemini Developer, en plus du type d'établissement et du tableau de pondération ci-dessus, vous pouvez disposer de données de description pour chaque établissement qui se présentent comme suit:

Ces descriptions qualitatives, ainsi que toutes les informations ou préférences utilisateur, peuvent être incluses dans votre requête à Gemini.

Instructions système

Gemini nécessite des instructions, ainsi que des données brutes, pour savoir qu'il doit générer un score pour chaque emplacement, en fonction des points de données fournis. Voici un exemple d'instruction système pour y parvenir:

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

Les instructions système ci-dessus indiquent à Gemini les données attendues et la sortie attendue du modèle d'IA. Elles demandent également la sortie au format JSON.

Résultat structuré

Bien que nous ayons demandé à Gemini de générer le résultat au format JSON, nous devons être plus précis sur la structure de la sortie afin de savoir à quoi nous attendre lorsque nous l'interrogeons avec du code. Pour ce faire, nous pouvons ajouter une instruction sortie structurée supplémentaire à la requête à l'aide du champ responseSchema dans l'API Gemini. Pour ce faire, un objet de schéma OpenAPI est utilisé pour contraindre la sortie du modèle.

Exemple :

{
  "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"
    ]
  }
}

Cet exemple demande à Gemini de générer un tableau JavaScript avec les éléments suivants:

• Latitude et longitude de l'établissement
• Note de l'emplacement personnalisé

En utilisant les instructions système et la sortie structurée ci-dessus, la réponse de Gemini pour un emplacement se présente comme suit, score étant le score de position personnalisé:

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

Afficher le score

Une fois que vous avez généré le score de lieu personnalisé pour chaque lieu à l'aide de l'une des méthodes décrites, vous pouvez l'afficher à côté des informations de votre hôtel ou l'utiliser comme option de filtrage de recherche. Par exemple, "Montre-moi les lieux avec un score élevé pour les touristes". Vos clients pourront ainsi prendre des décisions basées sur les données lors de leur réservation.

Conclusion

L'utilisation de scores d'emplacements personnalisés peut être un outil puissant pour donner à vos utilisateurs un aperçu de l'adéquation d'une zone. Ce document a montré comment générer des scores de lieu personnalisés pour différents lieux à l'aide de cinq types de lieux distincts. Cette implémentation peut être modifiée en fonction de vos besoins, et des types d'établissements similaires peuvent être combinés dans une seule requête pour renvoyer le nombre agrégé de ces types et le fournir à votre solution d'évaluation personnalisée des lieux.

Essayez l'API Places Aggregate dès aujourd'hui pour générer des scores de localisation pertinents et aider vos clients à prendre des décisions éclairées en fonction de leur position.

Contributeurs

Henrik Valve | Ingénieur DevX