Utilizzare l'API Places Aggregate per creare un punteggio della località personalizzato

Obiettivo

Trovare la posizione ideale, che si tratti di un hotel per le tue prossime vacanze o di un appartamento adatto alle famiglie, spesso comporta un processo frustrante e dispendioso in termini di tempo per confrontare numerose opzioni. E se potessi semplificare la vita ai tuoi utenti fornendo una metrica personalizzata che riveli l'idoneità di un hotel per i turisti o classificare gli annunci di appartamenti in base alla loro idoneità per le famiglie, trasformando un compito noioso in una decisione semplice.

Questo documento descrive come utilizzare l'API Places Aggregate per generare punteggi di località dinamici e personalizzati in base alla densità dei luoghi all'interno di un'area geografica definita. Il punteggio, una classificazione numerica in base ai criteri specificati, comunicherà immediatamente l'idoneità della posizione alle loro esigenze.

Considera uno scenario in cui promuovi hotel in una città e vuoi mettere in evidenza quelli nelle zone turistiche più attraenti creando un punteggio ideale per i turisti. Utilizza l'API Places Aggregate per conteggiare il numero di tipi di luoghi pertinenti vicino a ogni hotel. Ad esempio, sai che i tuoi clienti apprezzano gli hotel in località vicine a:

• Ristoranti e caffetterie
• Parchi e musei
• Negozi di abbigliamento

Applicando ponderazioni di importanza ai conteggi di questi tipi di luoghi selezionati, puoi calcolare un punteggio complessivo per ogni posizione dell'hotel. Il punteggio riflette l'idoneità complessiva della posizione, in base ai luoghi nelle vicinanze. Le ponderazioni assegnate a ogni tipo di luogo devono essere in linea con il tuo caso d'uso specifico e con ciò che è importante per il tuo pubblico di destinazione. Questo documento utilizzerà un punteggio adatto ai turisti come esempio principale, ma il tuo punteggio può essere creato in modo da riflettere i dati demografici e le esigenze degli utenti.

Prerequisiti

Prima di leggere questo documento, ti consigliamo di acquisire familiarità con la seguente documentazione:

• Documentazione per gli sviluppatori dell'API Places Aggregate per comprendere i dettagli tecnici e i parametri disponibili.
• [Facoltativo] Documentazione per sviluppatori dell'API Gemini Developer per capire come chiamare Gemini utilizzando un'API. Questa documentazione viene utilizzata in questo documento come opzione per generare il punteggio di posizione personalizzato.

Demo

Questa demo mostra un esempio del punteggio della località personalizzata in azione. Scegli una città dal menu a discesa e fai clic sul pulsante Calcola punteggio personalizzato per visualizzare il punteggio personalizzato della località per cinque località precompilate.

Seleziona i tipi di luoghi pertinenti

Il primo passo per creare il tuo punteggio personalizzato per località è decidere i tipi di luoghi pertinenti per i tuoi clienti dalla tabella A. Poiché stiamo creando un punteggio adatto ai turisti, abbiamo selezionato i seguenti tipi di luoghi che i turisti vorranno avere nelle vicinanze durante il loro soggiorno:

• ristorante
• parco
• clothing_store
• museo
• coffee_shop

Successivamente, assegna un peso a ciascuno di questi tipi di luogo, in modo da riflettere la sua importanza relativa nel punteggio finale. Le ponderazioni devono essere determinate in base a ciò che è più importante per il tuo caso d'uso e per le preferenze degli utenti. Per questo esempio, la scala di ponderazione sarà compresa tra 0 e 1, come segue:

Chiama l'API Places Aggregate

Ora che hai un elenco dei tipi di luoghi che ti interessano, il passaggio successivo è chiamare l'API Places Aggregate.

L'API Places Aggregate richiede un filtro della località. Per questo esempio, utilizza circle, con il centro latLng che corrisponde alla posizione del tuo hotel e un radius di 500 metri. Imposta anche ratingFilter per restituire luoghi con una valutazione compresa tra 3,8 e 5, escludendo dai conteggi i luoghi con una valutazione inferiore.

Prova a variare le impostazioni del filtro per la località per il tuo caso d'uso specifico. Ad esempio, potresti voler acquisire luoghi entro un raggio più ampio dalla latitudine e dalla longitudine del centro aumentando il valore del raggio. In alternativa, puoi utilizzare un metodo diverso per impostare l'area di ricerca, ad esempio Regione o Area personalizzata.

Acquisisci familiarità con la sezione relativa al filtro per località della documentazione dell'API Places Aggregate per scoprire le opzioni a tua disposizione.

Chiama l'API Places Aggregate per ogni tipo di luogo e posizione per cui vuoi generare un punteggio personalizzato. Ad esempio, chiama il tipo di luogo del ristorante per uno dei tuoi hotel:

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

Al termine di tutte le chiamate all'API, avrai dati simili a questi per ogni località:

Generare il punteggio della località personalizzata

Ora che hai il conteggio dei luoghi e la ponderazione per ogni tipo di luogo per ogni località, puoi generare il punteggio personalizzato della località. In questa sezione esamineremo due opzioni: l'utilizzo di un algoritmo locale o dell'API Gemini Developer.

Opzione 1: utilizza un algoritmo

La prima opzione che tratteremo è l'utilizzo di un algoritmo locale per generare un punteggio utilizzando le ponderazioni e i conteggi per ogni tipo di luogo. Normalizza questo punteggio su una scala da 0 a 5, dove valori più elevati indicano un'area più attraente in base ai tuoi criteri. Per questo esempio, genera due oggetti JavaScript dai dati riportati sopra:

    {
      "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 un punteggio dai conteggi e dalle ponderazioni moltiplicando itemCounts per typeWeights e aggiungendo i risultati a un weightedCount complessivo:

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

Per questo esempio, l'output di questo passaggio è 78,3.

Ora puoi utilizzare la normalizzazione logaritmica per generare il punteggio finale per questa località su una scala compresa tra 0 e 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));

Per questo esempio, l'output del punteggio finale è: 4,36 (arrotondato a due cifre decimali).

Opzione 2: utilizza l'API Gemini Developer

In alternativa all'utilizzo di un algoritmo locale, l'API Gemini Developer offre un modo efficace per calcolare il punteggio di località personalizzato per tutte le località. Basta fornire i dati di conteggio e ponderazione con le istruzioni di sistema per tutte le sedi degli hotel.

Questo metodo è particolarmente utile se hai informazioni dettagliate da includere nel calcolo, ad esempio:

• Descrizioni di testo per ogni posizione dell'hotel, ad esempio: "Questa posizione è adatta alle famiglie e la zona è tranquilla di notte".
• Informazioni sull'utente, ad esempio: "Questo utente sta prenotando per una famiglia e preferisce una zona tranquilla in una posizione centrale".

L'API Gemini Developer può comprendere e tenere conto di questi dati qualitativi, ottenendo un punteggio più sofisticato e pertinente rispetto a un approccio puramente matematico.

Utilizzando l'API Gemini Developer, oltre alla tabella dei tipi di luoghi e dei pesi riportata sopra, puoi avere dati di descrizione per ogni località simili a questi:

Queste descrizioni qualitative, insieme a eventuali informazioni o preferenze dell'utente, possono essere incluse nel prompt per Gemini.

Istruzioni di sistema

Gemini richiede istruzioni, insieme ai dati non elaborati, per sapere che deve generare un punteggio per ogni località, in base ai punti dati forniti. Un esempio di istruzione di sistema per ottenere questo risultato potrebbe essere il seguente:

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

Le istruzioni di sistema riportate sopra indicano a Gemini quali dati aspettarsi e qual è l'output previsto dal modello AI. Richiedono anche l'output in formato JSON.

Output strutturato

Anche se abbiamo chiesto a Gemini di restituire il risultato in formato JSON, dobbiamo essere più specifici sulla struttura dell'output, in modo da sapere cosa aspettarci quando lo interroghiamo con il codice. A questo scopo, possiamo aggiungere un'istruzione output strutturato alla richiesta, utilizzando il campo responseSchema nell'API Gemini. Utilizza un oggetto schema OpenAPI per vincolare l'output del modello.

Ad esempio:

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

Questo esempio richiede a Gemini di restituire un array JavaScript con quanto segue:

• Latitudine e longitudine della posizione
• Punteggio della posizione personalizzato

Utilizzando le istruzioni di sistema e l'output strutturato riportati sopra, la risposta di Gemini per una località sarebbe simile a questa, con score che rappresenta il punteggio personalizzato della località:

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

Visualizzare il punteggio

Una volta generato il punteggio personalizzato della località per ogni località utilizzando uno dei metodi descritti, può essere visualizzato insieme ai dettagli dell'hotel o utilizzato come opzione di filtro di ricerca. Ad esempio, "mostrami i luoghi con un punteggio adatto ai turisti elevato". In questo modo i tuoi clienti potranno prendere decisioni basate sui dati al momento della prenotazione.

Conclusione

L'utilizzo di punteggi personalizzati per le località può essere uno strumento efficace per fornire agli utenti una panoramica immediata dell'idoneità di un'area. Questo documento ha dimostrato la generazione di punteggi di località personalizzati per varie località utilizzando cinque tipi di luoghi separati. Questa implementazione può essere modificata in base alle tue esigenze e tipi di luoghi simili possono essere combinati in un'unica richiesta per restituire il conteggio aggregato di questi tipi, da fornire alla tua soluzione personalizzata di valutazione della posizione.

Prova oggi stesso l'API Places Aggregate per generare punteggi delle località utili per aiutare i tuoi clienti a prendere decisioni ben informate in base alla posizione.

Collaboratori

Henrik Valve | DevX Engineer