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

Objectif

Trouver l'endroit 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 chronophage de comparaison de nombreuses options. Imaginez pouvoir aider vos utilisateurs en leur fournissant une métrique personnalisée qui révèle si un hôtel est adapté aux touristes ou en classant les annonces d'appartements en fonction de leur convivialité pour les familles, transformant ainsi une corvée fastidieuse en une décision facile.

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

Imaginez que vous fassiez la promotion d'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 de lieux pertinents à proximité de chaque hôtel. Par exemple, vous savez que vos clients apprécient les hôtels situés à proximité de plusieurs 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 emplacement d'hôtel. Le 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 utilisera un score Bon pour les touristes comme exemple principal, mais votre score peut être conçu pour refléter les besoins et la démographie de vos utilisateurs.

Prérequis

Avant de lire ce document, il est recommandé de vous familiariser avec la documentation suivante :

• Consultez la documentation pour les développeurs de l'API Places Aggregate pour comprendre les détails techniques et les paramètres disponibles.
• [Facultatif] Consultez la documentation pour les développeurs de l'API Gemini afin de comprendre comment appeler Gemini à l'aide d'une API. Cette documentation est utilisée dans ce document comme option pour générer le score de localisation personnalisé.

Démo

Cette démo montre un exemple de score de localisation 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 lieux préremplis.

Sélectionnez les types de lieux concernés.

La première étape pour créer votre score de localisation personnalisé consiste à choisir les types de lieux qui intéressent vos clients dans le tableau A. Comme nous créons un score Bon pour les touristes, nous avons sélectionné les types de lieux suivants que les touristes souhaiteront trouver à proximité pendant leur séjour :

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

Ensuite, attribuez une pondération à 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. Dans 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 de lieux qui vous intéressent, l'étape suivante consiste à appeler l'API Places Aggregate.

L'API Places Aggregate nécessite un filtre de localisation. Pour cet exemple, utilisez circle, avec le centre latLng correspondant à l'emplacement de votre hôtel et un radius de 500 m. Définissez également ratingFilter pour renvoyer les lieux ayant une note comprise entre 3,8 et 5, en excluant les lieux ayant une note inférieure des décomptes.

Testez différentes valeurs pour le filtre de localisation 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 de votre 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 localisation de la documentation de l'API Places Aggregate pour découvrir les options à votre disposition.

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, appelez le type de lieu du 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 ressemblent à ceci pour chaque établissement :

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

Maintenant que vous disposez du nombre de lieux et de la pondération pour chaque type de lieu et pour chaque emplacement, vous pouvez générer le score personnalisé de l'emplacement. Dans cette section, nous aborderons deux options : l'utilisation d'un algorithme local ou l'utilisation de 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 nombres pour chaque type de lieu. Normalisez ce score sur une échelle de 0 à 5, où les valeurs les 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 le suivant : 78,3.

Vous pouvez désormais utiliser la normalisation logarithmique pour générer le score final de ce lieu sur une échelle comprise entre 0 et 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));

Dans cet exemple, le résultat final est le suivant : 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 puissant de calculer le score de localisation personnalisé pour tous les lieux. Il vous suffit de fournir les données de nombre et de pondération avec les 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 qu'une approche purement mathématique.

En utilisant l'API Gemini Developer, en plus du type de lieu et du tableau de pondération ci-dessus, vous pouvez obtenir des données de description pour chaque lieu, comme ceci :

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

Instructions système

Gemini a besoin d'instructions et de 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 le résultat attendu du modèle d'IA. Elles demandent également le résultat au format JSON.

Sortie structurée

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'interrogerons avec du code. Pour ce faire, nous pouvons ajouter une instruction structured output à la requête, en utilisant le champ responseSchema dans l'API Gemini. Il utilise un objet de schéma OpenAPI 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ée

En utilisant les instructions système et la sortie structurée ci-dessus, la réponse de Gemini pour un établissement se présente comme suit, avec score comme score personnalisé de l'établissement :

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

Afficher le score

Une fois que vous avez généré le score de localisation personnalisé pour chaque établissement à l'aide de l'une des méthodes décrites, vous pouvez l'afficher à côté des informations sur votre hôtel ou l'utiliser comme option de filtrage de la recherche. Par exemple, "montre-moi les lieux qui ont un score bien pour les touristes élevé". Cela permettra à vos clients de prendre des décisions basées sur des données lorsqu'ils effectueront une réservation.

Conclusion

L'utilisation de scores de localisation 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 localisation personnalisés pour différents lieux à l'aide de cinq types de lieux distincts. Cette implémentation peut être modifiée pour répondre à vos besoins. Des types de lieux similaires peuvent être combinés dans une même requête pour renvoyer le nombre agrégé de ces types et le fournir à votre solution de scoring personnalisé des lieux.

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

Contributeurs

Henrik Valve | Ingénieur DevX