Obiettivo
Trovare la località ideale, che si tratti di un hotel per la tua prossima vacanza o di un appartamento adatto a tutta la famiglia, spesso comporta un processo frustrante e dispendioso in termini di tempo per confrontare numerose opzioni. E se potessi semplificare questa operazione per i tuoi utenti fornendo una metrica personalizzata che rivela l'idoneità di un hotel per i turisti o classificando gli annunci di appartamenti in base alla loro idoneità per le famiglie, trasformando un'attività noiosa 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, un ranking numerico basato sui criteri specificati, comunicherà immediatamente l'idoneità della località alle loro esigenze.
Considera uno scenario in cui promuovi hotel in una città e vuoi mettere in evidenza quelli nelle zone turistiche più interessanti creando un punteggio di idoneità per i turisti. Utilizza l'API Places Aggregate per contare quanti tipi di luoghi pertinenti si trovano 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 località dell'hotel. Il punteggio riflette l'idoneità complessiva della località, 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 lo sviluppo dell'API Places Aggregate per comprendere i dettagli tecnici e i parametri disponibili.
- [Facoltativo] Documentazione per lo sviluppo dell'API Gemini Developer per capire come chiamare Gemini utilizzando un'API. Viene utilizzata in questo documento come opzione per generare il punteggio della località personalizzata.
Seleziona i tipi di luoghi pertinenti
Il primo passaggio per creare il punteggio della località personalizzato consiste nel 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 vicino ai quali i turisti vorranno trovarsi durante il loro soggiorno:
- ristorante
- parco
- clothing_store
- museo
- coffee_shop
Successivamente, assegna una ponderazione a ciascuno di questi tipi di luoghi, che rifletta 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 dell'utente. Per questo esempio, la scala di ponderazione sarà compresa tra 0 e 1, come segue:
Tipo di luogo |
Ponderazione |
ristorante |
0,8 |
parco |
0,6 |
clothing_store |
0,3 |
museo |
0,2 |
coffee_shop |
0,5 |
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 di località. 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 che restituisca i luoghi con una valutazione compresa tra 3,8 e 5, escludendo i luoghi con una valutazione inferiore dai conteggi.
Sperimenta modificando le impostazioni del filtro di località per il tuo caso d'uso specifico. Ad esempio, potresti voler acquisire luoghi entro un raggio più ampio dalla latitudine e dalla longitudine centrali aumentando il valore del raggio. In alternativa, puoi utilizzare un altro metodo per impostare l'area di ricerca, ad esempio Regione o Area personalizzata.
Acquisisci familiarità con la sezione dei filtri di 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 località per cui vuoi generare un punteggio personalizzato. Ad esempio, chiama il tipo di luogo 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
}
}
}'
Una volta completate tutte le chiamate all'API, i dati per ogni località saranno simili ai seguenti:
Tipo di luogo |
Ponderazione |
Conteggio |
ristorante |
0,8 |
56 |
parco |
0,6 |
3 |
clothing_store |
0,3 |
32 |
museo |
0,2 |
8 |
coffee_shop |
0,5 |
41 |
Genera il punteggio della località personalizzata
Ora che hai il numero di luoghi e la ponderazione per ogni tipo di luogo per ogni località, puoi generare il punteggio della località personalizzata. In questa sezione parleremo di due opzioni: l'utilizzo di un algoritmo locale o l'utilizzo dell'API Gemini Developer.
Opzione 1: utilizza un algoritmo
La prima opzione che esamineremo consiste nell'utilizzare 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 i valori più alti indicano un'area più interessante in base ai tuoi criteri. Per questo esempio, genera due oggetti JavaScript dai dati riportati sopra:
itemCounts |
typeWeights |
{ "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 il itemCounts
per il 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 della località personalizzata per tutte le località. Basta fornire i dati relativi al conteggio e alla ponderazione con le istruzioni di sistema per tutte le sedi degli hotel.
Questo metodo è particolarmente utile se hai informazioni dettagliate che vuoi includere nel calcolo, ad esempio:
- Descrizioni testuali per ogni località dell'hotel, ad esempio: "Questa località è 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, portando a un punteggio più sofisticato e pertinente che va oltre un approccio puramente matematico.
Utilizzando l'API Gemini Developer, oltre alla tabella dei tipi di luoghi e delle ponderazioni riportata sopra, puoi avere dati descrittivi per ogni località simili ai seguenti:
Località |
Descrizione |
Posizione centrale vicino ai musei, tranquilla di notte e adatta alle famiglie. |
|
Posizione centrale vicino a bar e ristoranti. Rumoroso e affollato di notte, adatto ai gruppi. |
|
Posizione residenziale lontana dal centro città. |
|
Posizione centrale vicino al fiume. Tranquillo di notte e adatto alle famiglie. |
|
Posizione residenziale lontana dal centro città. |
Queste descrizioni qualitative, insieme a eventuali informazioni o preferenze dell'utente, possono essere incluse nel prompt per 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 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 consentono a Gemini di sapere quali dati aspettarsi e qual è l'output previsto dal modello di AI. Richiede inoltre l'output in formato JSON.
Output strutturato
Anche se abbiamo chiesto a Gemini di restituire il risultato in JSON, dobbiamo essere più specifici sulla struttura dell'output, in modo da sapere cosa aspettarci quando lo interroghiamo con il codice. Per farlo, possiamo aggiungere un'ulteriore istruzione di 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"
]
}
}
In questo esempio, viene richiesto a Gemini di generare un array JavaScript con i seguenti elementi:
- Latitudine e longitudine della località
- Il punteggio della località personalizzata
Utilizzando le istruzioni di sistema e l'output strutturato riportati sopra, la risposta di Gemini per una località sarà simile alla seguente, con score che rappresenta il punteggio della località personalizzata:
[
{
"location": {
"latitude": 51.51611,
"longitude": -0.12726
},
"score": "4.13"
}
]
Mostra il punteggio
Dopo aver generato il punteggio della località personalizzato per ogni località utilizzando uno dei metodi descritti, questo può essere visualizzato insieme ai dettagli dell'hotel o utilizzato come opzione di filtro della ricerca. Ad esempio, "mostrami i luoghi con un punteggio elevato per adatto ai turisti". In questo modo, i tuoi clienti potranno prendere decisioni basate sui dati al momento della prenotazione.
Conclusione
L'utilizzo di punteggi delle località personalizzati può essere uno strumento efficace per offrire agli utenti una panoramica immediata dell'idoneità di un'area. Questo documento ha mostrato come generare punteggi di località personalizzati per varie località utilizzando cinque tipi di luoghi distinti. 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 di punteggio della posizione personalizzata.
Prova subito l'API Places Aggregate per generare punteggi di località approfonditi che aiutino i tuoi clienti a prendere decisioni basate sulla località ben informate.
Collaboratori
Henrik Valve | DevX Engineer