Scores de zones géographiques personnalisées Places Aggregate

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 de comparer de nombreuses options, ce qui peut être frustrant et chronophage. Et si vous pouviez faciliter la tâche de vos utilisateurs en leur fournissant une métrique personnalisée qui indique si un hôtel est adapté aux touristes ou en classant les annonces d'appartements en fonction de leur adéquation aux familles, transformant ainsi une corvée fastidieuse en une décision sans effort ?

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, un classement numérique basé sur les critères que vous avez spécifiés, indique instantanément si l'emplacement est adapté à leurs besoins.

Imaginons que vous promouviez 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 d'attractivité touristique. 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 au nombre 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 utilise un score adapté aux touristes comme exemple principal, mais votre score peut être conçu 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 vous familiariser avec la documentation suivante :

• Documentation pour les développeurs sur l'API Places Aggregate pour comprendre les détails techniques et les paramètres disponibles.
• [Facultatif] Documentation de l'API Gemini Developer 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 d'emplacement personnalisé.

Sélectionner les types de lieux pertinents

La première étape pour créer votre score de localisation personnalisé consiste à choisir les types de lieux pertinents pour vos clients dans le tableau A. Comme nous créons un score adapté aux touristes, nous avons sélectionné les types de lieux suivants dont les touristes voudront être proches pendant leur séjour :

• restaurant
• parc
• clothing_store
• musée
• coffee_shop

Ensuite, attribuez une pondération à chacun de ces types de lieux, reflétant son 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 des préférences de l'utilisateur. 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 de 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 lieu. 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 dont la note est comprise entre 3,8 et 5, en excluant les lieux moins bien notés du décompte.

Testez différents paramètres du filtre de localisation pour votre cas d'utilisation spécifique. Par exemple, vous pouvez capturer des lieux dans un rayon plus large à partir de votre latitude et de votre longitude centrales en augmentant la valeur du rayon. Vous pouvez également utiliser une autre méthode pour définir la zone de recherche, par exemple Région ou Zone personnalisée.

Familiarisez-vous avec la section sur les filtres de localisation 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, appelez 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 terminés, vous disposez de données qui ressemblent à ceci pour chaque établissement :

Générer le score d'emplacement personnalisé

Maintenant que vous disposez du nombre de lieux et de la pondération pour chaque type de lieu pour chaque emplacement, vous pouvez générer le score d'emplacement personnalisé. Dans cette section, nous allons aborder 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 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 le itemCounts par le 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 de 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 d'emplacement personnalisé pour tous les emplacements. Il vous suffit de fournir les données de décompte et de pondération avec des instructions système pour tous vos établissements hôteliers.

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

• Descriptions textuelles de chaque hôtel, par exemple : "Cet établissement est adapté aux familles et le quartier est calme la nuit".
• Informations sur l'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'avec 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 suit :

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

Instructions système

Gemini a besoin d'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 permettant d'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 permettent à Gemini de savoir quelles données attendre et quel est 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 du résultat afin de savoir à quoi nous attendre lorsque nous l'interrogeons avec du code. Pour ce faire, nous pouvons ajouter une instruction de sortie structurée supplémentaire à la requête, à l'aide du champ responseSchema de l'API Gemini. Cela utilise un objet de schéma OpenAPI pour limiter 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
• Le score 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 ressemblerait à ceci, score étant le score d'emplacement 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 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 recherche. Par exemple, "montre-moi des lieux avec un score élevé pour idéal pour les touristes". Vos clients pourront ainsi prendre des décisions basées sur les données lors de la réservation.

Conclusion

Les scores de localisation personnalisés sont un outil puissant qui permet de donner à vos utilisateurs un aperçu rapide de l'adéquation d'une zone. Ce document a montré comment générer des scores de localisation personnalisés pour différents emplacements à l'aide de cinq types de lieux distincts. Cette implémentation peut être modifiée en fonction de vos besoins. Vous pouvez combiner des types de lieux similaires dans une même requête pour renvoyer le nombre agrégé de ces types et le fournir à votre solution personnalisée de notation des emplacements.

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 basées sur la localisation.

Contributeurs

Henrik Valve | Ingénieur DevX