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

Obiettivo

Trovare la posizione ideale, che si tratti di un hotel per la tua prossima vacanza o di un appartamentino adatto alle famiglie, spesso comporta un processo frustrante e che richiede molto tempo per confrontare numerose opzioni. E se potessi semplificare la vita ai tuoi utenti fornendo una metrica personalizzata che indichi l'idoneità di un hotel per i turisti o che classifichi le schede degli appartamenti in base alla loro idoneità per le famiglie, trasformando un'attività noiosa in una decisione facile?

Questo documento illustra come utilizzare l'API Places Aggregate per generare punteggi dinamici e personalizzati per le località, in base alla densità dei luoghi all'interno di un'area geografica definita. Il voto, un ranking numerico in base ai criteri specificati, comunicherà immediatamente quanto la stazione di ricarica è adatta alle loro esigenze.

Immagina di promuovere hotel in una città e di voler mettere in evidenza quelli nelle aree turistiche più interessanti creando un punteggio per i turisti. Utilizza l'API Places Aggregate per conteggiare il numero di tipi di luoghi pertinenti nelle vicinanze di ogni hotel. Ad esempio, sai che i tuoi clienti apprezzano gli hotel in località situate nelle vicinanze di diversi elementi tra i seguenti:

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

Applicando i pesi di importanza ai conteggi di questi tipi di luoghi selezionati, puoi calcolare un punteggio complessivo per ogni località dell'hotel. Il punteggio riflette la idoneità complessiva della stazione di ricarica in base ai luoghi nelle vicinanze. I coefficienti assegnati 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 ideale per i turisti come esempio principale, ma il tuo punteggio può essere creato in base ai dati demografici e alle esigenze dei tuoi utenti.

Prerequisiti

Prima di leggere questo documento, ti consigliamo di familiarizzare con la seguente documentazione:

• La documentazione per gli sviluppatori dell'API Places Aggregate per comprendere i dettagli tecnici e i parametri disponibili.
• [Facoltativo] Documentazione per gli sviluppatori dell'API Gemini Developer per capire come chiamare Gemini utilizzando un'API e utilizzata in questo documento come opzione per generare il punteggio della località personalizzata.

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 della località personalizzata per cinque località precompilate.

Seleziona i tipi di luoghi pertinenti

Il primo passaggio per creare il punteggio della località personalizzata consiste nel decidere i tipi di luoghi pertinenti per i tuoi clienti riportati nella Tabella A. Poiché stiamo creando un punteggio ideale per i turisti, abbiamo selezionato i seguenti tipi di luoghi in cui i turisti vorranno soggiornare durante il loro soggiorno:

• ristorante
• parco
• clothing_store
• museo
• coffee_shop

Assegna poi un peso a ciascuno di questi tipi di luoghi, in base alla relativa importanza nel punteggio finale. I pesi devono essere determinati in base a ciò che è più importante per il tuo caso d'uso e per le preferenze dell'utente. 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 di tipi di luoghi che ti interessano, il passaggio successivo è chiamare l'API Places Aggregate.

L'API Places Aggregate richiede un filtro posizione. Per questo esempio, utilizza circle, con il centro latLng che corrisponde alla posizione del tuo hotel e un radius di 500 m. Imposta anche ratingFilter in modo da restituire i luoghi con una valutazione compresa tra 3,8 e 5, escludendo dal conteggio i luoghi con una valutazione inferiore.

Prova a modificare le impostazioni del filtro posizione per il tuo caso d'uso specifico. Ad esempio, potresti voler acquisire luoghi all'interno di un raggio più ampio rispetto alla latitudine e alla longitudine del centro aumentando il valore del raggio. In alternativa, puoi utilizzare un metodo diverso per impostare l'area di ricerca, come Regione o Area personalizzata.

Consulta la sezione relativa al filtro dei luoghi della documentazione dell'API aggregate di Places per scoprire le opzioni a tua disposizione.

Chiama l'API Places Aggregate per ogni tipo di luogo e località per cui vuoi generare un punteggio personalizzato. Ad esempio, richiedi 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à:

Genera 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 della località personalizzata. In questa sezione illustreremo due opzioni: l'utilizzo di un algoritmo locale o dell'API Developer di Gemini.

Opzione 1: utilizza un algoritmo

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

    {
      "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, il 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 Developer di Gemini offre un modo efficace per calcolare il punteggio della località personalizzata per tutte le località. Fornisci semplicemente i dati relativi al conteggio e alla ponderazione con le istruzioni di sistema per tutte le sedi dei tuoi 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 struttura è adatta alle famiglie e la zona è tranquilla di notte".
• Informazioni sull'utente, ad esempio: "Questo utente sta prenotando per una famiglia e preferisce un'area tranquilla in una posizione centrale".

L'API Gemini Developer è in grado di comprendere e prendere in considerazione questi dati qualitativi, in modo da ottenere un punteggio più sofisticato e pertinente rispetto a un approccio puramente matematico.

Utilizzando l'API Gemini Developer, oltre al tipo di luogo e alla tabella di ponderazione sopra riportata, puoi avere dati descrittivi per ogni località come segue:

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

Istruzioni di sistema

Gemini richiede istruzioni, oltre 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 la 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 consentono a Gemini di sapere quali dati aspettarsi e qual è l'output previsto del modello di IA. Richiede inoltre l'output in JSON.

Output strutturato

Abbiamo chiesto a Gemini di generare il risultato in JSON, ma dobbiamo essere più specifici sulla struttura dell'output per sapere cosa aspettarci quando eseguiamo query con il codice. Per farlo, possiamo aggiungere un'istruzione structured output aggiuntiva alla richiesta, utilizzando il campo responseSchema nell'API Gemini. Viene utilizzato un oggetto schema OpenAPI per limitare 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"
    ]
  }
}

In questo esempio viene richiesto a Gemini di generare un array JavaScript con quanto segue:

• Latitudine e longitudine della località
• Il punteggio della località personalizzata

Utilizzando le istruzioni di sistema e l'output strutturato riportate sopra, la risposta di Gemini per una località sarà simile a questa, dove score è il punteggio della località personalizzata:

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

Visualizza il punteggio

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

Conclusione

L'utilizzo dei punteggi delle località personalizzate può essere uno strumento efficace per offrire agli utenti una panoramica immediata dell'idoneità di un'area. Questo documento ha dimostrato come generare punteggi delle località personalizzati per varie località utilizzando cinque tipi di luoghi distinti. Questa implementazione può essere modificata in base alle tue esigenze e i tipi di luoghi simili possono essere combinati in un'unica richiesta per restituire il conteggio aggregato di questi tipi e fornire la soluzione di punteggio della posizione personalizzata.

Prova oggi stesso l'API Places Aggregate per generare utili valutazioni della posizione e aiutare i tuoi clienti a prendere decisioni consapevoli in base alla località.

Collaboratori

Henrik Valve | DevX Engineer