Creare punteggi di località personalizzati con Places Insights

Panoramica

I dati sulla posizione standard possono dirti cosa c'è nelle vicinanze, ma spesso non riescono a rispondere alla domanda più importante: "Quanto è adatta questa zona a me?" Le esigenze dei tuoi utenti sono sfumate. Una famiglia con bambini piccoli ha priorità diverse rispetto a un giovane professionista con un cane. Per aiutarli a prendere decisioni consapevoli, devi fornire approfondimenti che riflettano queste esigenze specifiche. Un punteggio personalizzato della località è uno strumento efficace per offrire questo valore e creare un'esperienza utente differenziata significativa.

Questo documento descrive come creare punteggi di località personalizzati e sfaccettati utilizzando il set di dati Places Insights in BigQuery. Trasformando i dati dei PDI in metriche significative, puoi arricchire le tue applicazioni immobiliari, di vendita al dettaglio o di viaggi e fornire ai tuoi utenti le informazioni pertinenti di cui hanno bisogno. Forniamo anche un'opzione per utilizzare l'API Gemini Developer come modo efficace per calcolare i punteggi di posizione.

Aumentare il valore aziendale con i punteggi personalizzati

I seguenti esempi mostrano come tradurre i dati sulla posizione non elaborati nelle metriche potenti e incentrate sull'utente per migliorare l'applicazione.

• Gli sviluppatori immobiliari possono creare un "Punteggio di idoneità per le famiglie" o un "Punteggio ideale per i pendolari" per aiutare acquirenti e affittuari a scegliere il quartiere perfetto per il loro stile di vita, il che porta a un maggiore coinvolgimento degli utenti, lead di qualità superiore e conversioni più rapide.
• Gli ingegneri del settore viaggi e ospitalità possono creare un "punteggio della vita notturna" o un "punteggio del paradiso dei turisti" per aiutare i viaggiatori a scegliere un hotel che corrisponda al loro stile di vacanza, aumentando i tassi di prenotazione e la soddisfazione dei clienti
• Gli analisti del settore della vendita al dettaglio possono generare un "punteggio di fitness e benessere" per identificare la posizione ottimale per una nuova palestra o un nuovo negozio di alimenti biologici in base alle attività complementari nelle vicinanze, massimizzando il potenziale di targeting del giusto segmento demografico di utenti.

In questa guida imparerai una metodologia flessibile in tre parti per creare qualsiasi tipo di punteggio di località personalizzato utilizzando i dati di Places direttamente in BigQuery. Illustreremo questo pattern creando due punteggi di esempio distinti: un punteggio di idoneità per le famiglie e un punteggio di paradiso per i proprietari di animali domestici. Questo approccio ti consente di andare oltre i conteggi dei luoghi e sfruttare gli attributi ricchi e dettagliati all'interno del set di dati Approfondimenti di Places. Puoi utilizzare informazioni come l'orario di apertura, se un luogo è adatto ai bambini o se ammette i cani, per creare metriche sofisticate e significative per i tuoi utenti.

Flusso di lavoro della soluzione

Questo tutorial utilizza una singola e potente query SQL per creare un punteggio personalizzato che puoi adattare a qualsiasi caso d'uso. Esamineremo questo processo creando i due punteggi di esempio per un insieme ipotetico di schede di appartamenti.

Prerequisiti

Prima di iniziare, segui queste istruzioni per configurare Places Insights.

1. Crea una base: le tue località di interesse

Prima di poter creare i punteggi, devi avere un elenco delle sedi che vuoi analizzare. Il primo passaggio consiste nell'assicurarsi che questi dati esistano come tabella in BigQuery. La chiave è avere un identificatore univoco per ogni posizione e una colonna GEOGRAPHY che memorizzi le relative coordinate.

Puoi creare e compilare una tabella di località da valutare con una query come questa:

CREATE OR REPLACE TABLE `your_project.your_dataset.apartment_listings`
(
  id INT64,
  name STRING,
  location GEOGRAPHY
);

INSERT INTO `your_project.your_dataset.apartment_listings` VALUES
  (1, 'The Downtowner', ST_GEOGPOINT(-74.0077, 40.7093)),
  (2, 'Suburban Oasis', ST_GEOGPOINT(-73.9825, 40.7507)),
  (3, 'Riverside Lofts', ST_GEOGPOINT(-73.9470, 40.8079))
  -- More rows can be added here
  . . . ;

L'esecuzione di un SELECT * sui dati sulla posizione sarebbe simile a questa.

2. Sviluppa la logica principale: la query di assegnazione del punteggio

Una volta stabilite le località, il passaggio successivo consiste nel trovare, filtrare e conteggiare i luoghi nelle vicinanze pertinenti al tuo punteggio personalizzato. Tutto questo avviene in una singola istruzione SELECT.

Trovare cosa c'è nelle vicinanze con una ricerca geospaziale

Per prima cosa, devi trovare tutti i luoghi del set di dati Places Insights che si trovano a una determinata distanza da ciascuna delle tue sedi. La funzione BigQuery ST_DWITHIN è perfetta per questo. Eseguiremo un JOIN tra la nostra tabella apartment_listings e la tabella places_insights per trovare tutti i luoghi entro un raggio di 800 metri. Un LEFT JOIN garantisce che tutte le tue posizioni originali siano incluse nei risultati, anche se non vengono trovati luoghi corrispondenti nelle vicinanze.

Filtrare per pertinenza con gli attributi avanzati

Qui traduci il concetto astratto di un punteggio in filtri di dati concreti. Per i nostri due punteggi di esempio, i criteri sono diversi:

• Per il "Punteggio di idoneità per le famiglie", ci interessano parchi, musei e ristoranti esplicitamente adatti ai bambini.
• Per il "Punteggio paradiso dei proprietari di animali domestici", prendiamo in considerazione parchi, cliniche veterinarie, negozi per animali e qualsiasi ristorante o bar che ammetta cani.

Puoi filtrare questi attributi specifici direttamente nella clausola WHERE della query.

Aggregare gli approfondimenti per ogni località

Infine, devi contare quanti luoghi pertinenti hai trovato per ogni appartamento. La clausola GROUP BY aggrega i risultati e la funzione COUNTIF conta i luoghi che corrispondono ai criteri specifici per ciascuno dei nostri punteggi.

La query seguente combina questi tre passaggi, calcolando i conteggi non elaborati per entrambi i punteggi in un unico passaggio:

-- This Common Table Expression (CTE) will hold the raw counts for each score component.
WITH insight_counts AS (
  SELECT WITH AGGREGATION_THRESHOLD -- Correctly includes the mandatory aggregation threshold
    apartments.id,
    apartments.name,
    COUNTIF(places.primary_type = 'park') AS park_count,
    COUNTIF(places.primary_type = 'museum') AS museum_count,
    COUNTIF(places.primary_type = 'restaurant' AND places.good_for_children = TRUE) AS family_restaurant_count,
    COUNTIF(places.primary_type IN ('veterinary_care', 'pet_store')) AS pet_service_count,
    COUNTIF(places.allows_dogs = TRUE) AS dog_friendly_place_count
  FROM
    `your_project.your_dataset.apartment_listings` AS apartments
  LEFT JOIN
    `your-project.places_insights___us.places` AS places -- Corrected table name for the US dataset
    ON ST_DWITHIN(apartments.location, places.point, 800) -- Find places within 800 meters
  GROUP BY
    apartments.id, apartments.name
)
SELECT * FROM insight_counts;

Il risultato di questa query sarà simile a questo.

Approfondiremo questi risultati nella sezione successiva.

3. Creare il punteggio

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: utilizzare il tuo calcolo personalizzato in BigQuery o utilizzare l'API Gemini Developer.

Opzione 1: utilizza il tuo calcolo personalizzato in BigQuery

I conteggi non elaborati del passaggio precedente sono utili, ma l'obiettivo è ottenere un unico punteggio facile da usare. L'ultimo passaggio consiste nel combinare questi conteggi utilizzando i pesi e normalizzare il risultato su una scala da 0 a 10.

Applicare ponderazioni personalizzate: la scelta delle ponderazioni è sia un'arte che una scienza. Devono riflettere le priorità della tua attività o ciò che ritieni sia più importante per i tuoi utenti. Per un punteggio di "Idoneità per le famiglie", potresti decidere che un parco è due volte più importante di un museo. Inizia con le tue migliori ipotesi e itera in base al feedback degli utenti.

Normalizzazione del punteggio La query seguente utilizza due espressioni di tabella comune (CTE): la prima calcola i conteggi non elaborati come prima, mentre la seconda calcola i punteggi ponderati. L'istruzione SELECT finale esegue quindi una normalizzazione min-max sui punteggi ponderati. Viene restituita la colonna location della tabella apartment_listings di esempio, per consentire la visualizzazione dei dati su una mappa.

WITH
  -- CTE 1: Count nearby amenities of interest for each apartment listing.
  insight_counts AS (
    SELECT WITH AGGREGATION_THRESHOLD
      apartments.id,
      apartments.name,
      COUNTIF(places.primary_type = 'park') AS park_count,
      COUNTIF(places.primary_type = 'museum') AS museum_count,
      COUNTIF(places.primary_type = 'restaurant' AND places.good_for_children = TRUE) AS family_restaurant_count,
      COUNTIF(places.primary_type IN ('veterinary_care', 'pet_store')) AS pet_service_count,
      COUNTIF(places.allows_dogs = TRUE) AS dog_friendly_place_count
    FROM
      `your_project.your_dataset.apartment_listings` AS apartments
    LEFT JOIN
      `your-project.places_insights___us.places` AS places
      ON ST_DWITHIN(apartments.location, places.point, 800)
    GROUP BY
      apartments.id,
      apartments.name
  ),
  -- CTE 2: Apply custom weighting to the amenity counts to generate raw scores.
  raw_scores AS (
    SELECT
      id,
      name,
      (park_count * 3.0) + (museum_count * 1.5) + (family_restaurant_count * 2.5) AS family_friendliness_score,
      (park_count * 2.0) + (pet_service_count * 3.5) + (dog_friendly_place_count * 2.5) AS pet_paradise_score
    FROM
      insight_counts
  )
-- Final Step: Normalize scores to a 0-10 scale and rejoin to retrieve the location geometry.
SELECT
  raw_scores.id,
  raw_scores.name,
  apartments.location,
  raw_scores.family_friendliness_score,
  raw_scores.pet_paradise_score,
  -- Normalize Family Score using a MIN/MAX window function.
  ROUND(
    COALESCE(
      SAFE_DIVIDE(
        (raw_scores.family_friendliness_score - MIN(raw_scores.family_friendliness_score) OVER ()),
        (MAX(raw_scores.family_friendliness_score) OVER () - MIN(raw_scores.family_friendliness_score) OVER ())
      ) * 10,
      0
    ),
    2
  ) AS normalized_family_score,
  -- Normalize Pet Score using a MIN/MAX window function.
  ROUND(
    COALESCE(
      SAFE_DIVIDE(
        (raw_scores.pet_paradise_score - MIN(raw_scores.pet_paradise_score) OVER ()),
        (MAX(raw_scores.pet_paradise_score) OVER () - MIN(raw_scores.pet_paradise_score) OVER ())
      ) * 10,
      0
    ),
    2
  ) AS normalized_pet_score
FROM
  raw_scores
JOIN
  `your_project.your_dataset.apartment_listings` AS apartments
  ON raw_scores.id = apartments.id;

I risultati della query saranno simili a quelli riportati di seguito. Le ultime due colonne sono i punteggi normalizzati.

Informazioni sul punteggio normalizzato

È importante capire perché questo passaggio finale di normalizzazione è così prezioso. I punteggi ponderati non elaborati possono variare da 0 a un numero potenzialmente molto elevato a seconda della densità urbana delle tue località. Un punteggio di 500 non ha significato per un utente senza contesto.

La normalizzazione trasforma questi numeri astratti in una classificazione relativa. Scalando i risultati da 0 a 10, il punteggio comunica chiaramente il confronto tra le varie sedi nel tuo set di dati specifico:

• Un punteggio di 10 viene assegnato alla posizione con il punteggio grezzo più alto, che viene contrassegnata come l'opzione migliore nel set corrente.
• Un punteggio pari a 0 viene assegnato alla località con il punteggio grezzo più basso, che diventa la base di riferimento per il confronto. Ciò non significa che la posizione non abbia servizi, ma piuttosto che è la meno adatta rispetto alle altre opzioni in fase di valutazione.
• Tutti gli altri punteggi si trovano proporzionalmente nel mezzo, offrendo agli utenti un modo chiaro e intuitivo per confrontare le opzioni a colpo d'occhio.

Opzione 2: utilizza l'API Gemini Developer

In alternativa all'utilizzo di una formula matematica fissa in BigQuery, l'API Gemini Developer offre un modo efficace per calcolare punteggi di posizione personalizzati e sfumati.

Sebbene l'opzione 1 sia eccellente per l'assegnazione di punteggi puramente quantitativi basati sul conteggio dei servizi, non può tenere facilmente conto dei dati qualitativi. Utilizzando Gemini, puoi combinare i numeri della query Approfondimenti di Places con dati non strutturati, ad esempio la descrizione testuale dell'annuncio di appartamenti (ad es. "Questa posizione è adatta alle famiglie e la zona è tranquilla di notte") o preferenze specifiche del profilo utente (ad es. "Questo utente sta prenotando per una famiglia e preferisce una zona tranquilla in una posizione centrale") per generare un punteggio più sfumato.

Preparare i dati per Gemini

Per utilizzare questo metodo, trasforma i risultati dell'aggregazione BigQuery (dal passaggio 2) in formato Markdown e combinali con i dati qualitativi, ad esempio un Listing Description.

In questo esempio, abbiamo due schede con caratteristiche molto diverse. Includiamo anche un Target User Profile per comunicare a Gemini per chi stiamo valutando questi contenuti:

## Listing 1: The Downtowner

*   **ID:** 1
*   **Amenity Counts:**
    *   Parks: 70
    *   Museums: 34
    *   Family-Friendly Restaurants: 141
*   **Listing Description:** A vibrant apartment in the heart of the city.
    Great for nightlife, but can be noisy on weekends. Close to several
    small playgrounds.
*   **Target User Profile:** Young family with a toddler, looking for a
    balance of activity and quiet.

---

## Listing 2: Suburban Oasis

*   **ID:** 2
*   **Amenity Counts:**
    *   Parks: 34
    *   Museums: 30
    *   Family-Friendly Restaurants: 318
*   **Listing Description:** Quiet, tree-lined street. Large backyard and easy
    walking distance to a major park and elementary school.
*   **Target User Profile:** Young family with a toddler, looking for a
    balance of activity and quiet.

Istruzioni di sistema

Gemini richiede istruzioni di sistema per sapere come valutare questi diversi punti dati. Puoi indicare esplicitamente al modello l'importanza di servizi specifici, chiedendogli anche di tenere conto del sentiment delle descrizioni testuali.

You are an expert real estate analyst. Your goal is to generate a
"Family-Friendliness Score" between 0.0 and 10.0 for a list of apartment
locations.

For each location, you will be given quantitative data (amenity counts)
and qualitative data (descriptions and user profiles).

Scoring Criteria:
-   High importance: Proximity to parks and a high count of family-friendly
    restaurants.
-   Medium importance: Proximity to museums.
-   Negative modifiers: Descriptions indicating excessive noise, lack of
    safe play areas, or mismatch with the user profile.
-   Positive modifiers: Descriptions indicating quiet areas, safe streets,
    or extra space (e.g., backyards).

Analyze the provided data and generate scores based on these criteria.

Output strutturato

Per garantire l'affidabilità quando integri l'AI nella tua applicazione, non devi fare affidamento solo sui prompt per il formato di output. Utilizza invece la funzionalità di output strutturato di Gemini. Fornendo un responseSchema, garantisci che il modello restituisca un array JSON pulito e analizzabile che corrisponda ai tuoi requisiti di sistema esatti.

Per il nostro esempio, possiamo applicare il seguente schema:

{
  "type": "ARRAY",
  "items": {
    "type": "OBJECT",
    "required": ["location_id", "name", "score", "reasoning"],
    "properties": {
      "location_id": {"type": "STRING"},
      "name": {"type": "STRING"},
      "score": {
        "type": "NUMBER"
      },
      "reasoning": {
        "type": "STRING"
      }
    }
  }
}

Output di esempio

Quando invii il prompt con il responseSchema definito, Gemini restituisce un array JSON strutturato pronto per essere utilizzato direttamente dalla tua applicazione.

Nell'output, nota come Gemini gestisce i compromessi. "The Downtowner" ha un numero incredibilmente elevato di parchi, ma Gemini identifica la descrizione "rumoroso nei fine settimana" come un aspetto negativo importante per un bambino piccolo. Nel frattempo, "Suburban Oasis" ottiene un punteggio quasi perfetto combinando un'eccellente densità di servizi con caratteristiche qualitative applicabili come "strada tranquilla e alberata".

[
  {
    "id": 1,
    "location_name": "The Downtowner",
    "analysis_notes": "Excellent amenity counts (parks, restaurants, museums), fulfilling
    quantitative metrics. However, the qualitative data indicates excessive weekend
    noise and a strong nightlife focus, conflicting directly with the target
    user's need for quiet and suitability for a toddler. This mismatch
    significantly lowers the final score.",
    "family_friendliness_score": 5.5
  },
  {
    "id": 2,
    "location_name": "Suburban Oasis",
    "analysis_notes": "Outstanding quantitative data, especially the very high count of
    family-friendly restaurants. The qualitative description (quiet, tree-lined street,
    large backyard, proximity to elementary school and major park) aligns perfectly with
    and exceeds the needs of the target family profile. High positive modifiers
    result in a near-perfect score.",
    "family_friendliness_score": 9.8
  }
]

Questo metodo ti consente di fornire un punteggio altamente personalizzato, comprensibile e su misura per ogni singolo utente.

4. Visualizzare i punteggi su una mappa

BigQuery Studio include una visualizzazione della mappa integrata per qualsiasi risultato di query che contenga una colonna GEOGRAPHY. Poiché la nostra query restituisce la colonna location, puoi visualizzare immediatamente i tuoi punteggi.

Se fai clic sulla scheda Visualization, viene visualizzata la mappa e il menu a discesa Data Column controlla il punteggio della posizione da visualizzare. In questo esempio, il normalized_pet_score viene visualizzato dall'esempio dell'opzione 1. Tieni presente che in questo esempio sono state aggiunte altre località alla tabella apartment_listings.

La visualizzazione dei dati rivela a colpo d'occhio le posizioni più appropriate per il punteggio creato, con cerchi verdi più scuri che rappresentano le posizioni con un normalized_pet_score più elevato, in questo caso. Per ulteriori opzioni di visualizzazione dei dati di Places Insights, consulta Visualizzare i risultati della query.

Conclusione

Ora disponi di una metodologia potente e ripetibile per creare punteggi di localizzazione sfumati. Partendo dalle tue località, hai creato una singola query SQL in BigQuery che trova i luoghi nelle vicinanze con ST_DWITHIN, li filtra in base ad attributi avanzati come good_for_children e allows_dogs e aggrega i risultati con COUNTIF. Applicando pesi personalizzati e normalizzando il risultato, hai ottenuto un unico punteggio intuitivo che fornisce informazioni approfondite e utili. Puoi applicare direttamente questo pattern per trasformare i dati sulla posizione non elaborati in un vantaggio competitivo significativo.

Azioni successive

Ora tocca a te creare. Questo tutorial fornisce un modello. Puoi utilizzare i dati avanzati disponibili nello schema Places Insights per creare i punteggi più necessari per il tuo caso d'uso. Prendi in considerazione questi altri punteggi che potresti creare:

• "Punteggio vita notturna": combina i filtri per primary_type (bar, night_club), price_level e orari di apertura a tarda notte per trovare le zone più vivaci dopo il tramonto.
• "Punteggio salute e fitness": conta le gyms, i parks e i health_food_stores nelle vicinanze e filtra i ristoranti in base a quelli con serves_vegetarian_food per assegnare un punteggio alle località per gli utenti attenti alla salute.
• "Punteggio da pendolare ideale": trova luoghi con un'alta densità di transit_station e parking nelle vicinanze per aiutare gli utenti che apprezzano l'accesso ai trasporti.

Collaboratori

Henrik Valve | DevX Engineer