Visão geral
Os dados de localização padrão podem informar o que está por perto, mas geralmente não respondem à pergunta mais importante: "Quão boa é essa área para mim?" As necessidades dos seus usuários são complexas. Uma família com crianças pequenas tem prioridades diferentes de um jovem profissional com um cachorro. Para ajudar os usuários a tomar decisões confiantes, você precisa fornecer insights que reflitam essas necessidades específicas. Uma pontuação de local personalizada é uma ferramenta eficiente para oferecer esse valor e criar uma experiência do usuário diferenciada e significativa.
Neste documento, descrevemos como criar pontuações de local personalizadas e multifacetadas usando o conjunto de dados Insights de lugares no BigQuery. Ao transformar dados de PDI em métricas significativas, você pode enriquecer seus aplicativos de imóveis, varejo ou viagens e fornecer aos usuários as informações relevantes de que eles precisam. Também oferecemos uma opção para usar a API Gemini Developer como uma maneira eficiente de calcular suas pontuações de localização.
Gerar valor comercial com pontuações personalizadas
Os exemplos a seguir mostram como traduzir dados de localização brutos em métricas poderosas e centradas no usuário para melhorar seu aplicativo.
- Os incorporadores imobiliários podem criar uma "Pontuação de adequação para famílias" ou uma "Pontuação de sonho do viajante" para ajudar compradores e locatários a escolher o bairro perfeito que corresponda ao estilo de vida deles, o que aumenta o engajamento do usuário, gera leads de maior qualidade e conversões mais rápidas.
- Os engenheiros de viagens e hotelaria podem criar uma "Pontuação de vida noturna" ou uma "Pontuação de paraíso para turistas" para ajudar os viajantes a escolher um hotel que corresponda ao estilo de férias deles, aumentando as taxas de reserva e a satisfação do cliente.
- Os analistas de varejo podem gerar uma "Pontuação de fitness e bem-estar" para identificar o local ideal de uma nova academia ou loja de alimentos saudáveis com base em empresas complementares próximas, maximizando o potencial de segmentação do público-alvo certo.
Neste guia, você vai aprender uma metodologia flexível de três partes para criar qualquer tipo de pontuação de local personalizada usando dados do Places diretamente no BigQuery. Vamos ilustrar esse padrão criando duas pontuações de exemplo distintas: uma Pontuação de adequação para famílias e uma Pontuação de paraíso para donos de animais de estimação. Com essa abordagem, é possível ir além das contagens de lugares e aproveitar os atributos detalhados e completos do conjunto de dados do Places Insights. Você pode usar informações como horário de funcionamento, se um lugar é bom para crianças ou se permite animais de estimação para criar métricas sofisticadas e significativas para seus usuários.
Fluxo de trabalho da solução
Este tutorial usa uma única consulta SQL eficiente para criar uma pontuação personalizada que você pode adaptar a qualquer caso de uso. Vamos explicar esse processo criando dois exemplos de pontuações para um conjunto hipotético de anúncios de apartamentos.
Pré-requisitos
Antes de começar, siga estas instruções para configurar o Places Insights.
1. Estabelecer uma base: seus locais de interesse
Antes de criar pontuações, você precisa de uma lista dos locais que quer analisar. A primeira etapa é garantir que esses dados existam como uma tabela no BigQuery.
A chave é ter um identificador exclusivo para cada local e uma coluna GEOGRAPHY que armazena as coordenadas.
É possível criar e preencher uma tabela de locais para pontuar com uma consulta como esta:
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
. . . ;
Realizar um SELECT * nos seus dados de local seria semelhante a isto.
2. Desenvolver a lógica principal: a consulta de pontuação
Com os locais definidos, a próxima etapa é encontrar, filtrar e contar os lugares próximos relevantes para sua pontuação personalizada. Tudo isso é feito em uma única instrução SELECT.
Encontrar o que está por perto com uma pesquisa geoespacial
Primeiro, encontre todos os lugares do conjunto de dados do Places Insights que estão a uma determinada distância de cada um dos seus locais. A função ST_DWITHIN do BigQuery é perfeita para isso. Vamos realizar uma JOIN entre as tabelas apartment_listings e places_insights para encontrar todos os lugares em um raio de 800 metros. Um LEFT JOIN garante que todos os seus locais originais sejam incluídos nos resultados, mesmo que não haja lugares correspondentes nas proximidades.
Filtrar por relevância com atributos avançados
É aqui que você traduz o conceito abstrato de uma pontuação em filtros de dados concretos. Para nossas duas pontuações de exemplo, os critérios são diferentes:
- Para a "Pontuação de adequação para famílias", consideramos parques, museus e restaurantes que são explicitamente bons para crianças.
- Para a "Pontuação de paraíso para donos de animais de estimação", consideramos parques, clínicas veterinárias, pet shops e qualquer restaurante ou café que permita a entrada de cães.
É possível filtrar esses atributos específicos diretamente na cláusula WHERE da consulta.
Agregar os insights de cada local
Por fim, conte quantos lugares relevantes você encontrou para cada apartamento. A cláusula GROUP BY agrega os resultados, e a função COUNTIF conta os lugares que correspondem aos critérios específicos de cada uma das nossas pontuações.
A consulta abaixo combina essas três etapas, calculando as contagens brutas para as duas pontuações em uma única passagem:
-- 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;
O resultado dessa consulta será semelhante a este.
Vamos usar esses resultados na próxima seção.
3. Criar a pontuação
Agora você tem a contagem de lugares e a ponderação de cada tipo de lugar para cada local. Assim, é possível gerar a pontuação de local personalizada. Nesta seção, vamos discutir duas opções: usar seu próprio cálculo personalizado no BigQuery ou usar a API Gemini para desenvolvedores.
Opção 1: usar seu próprio cálculo personalizado no BigQuery
As contagens brutas da etapa anterior são úteis, mas o objetivo é uma única pontuação fácil de usar. A etapa final é combinar essas contagens usando ponderações e normalizar o resultado em uma escala de 0 a 10.
Como aplicar ponderações personalizadas: escolher as ponderações é uma arte e uma ciência. Elas precisam refletir as prioridades da sua empresa ou o que você acredita ser mais importante para seus usuários. Para uma pontuação de "Adequação à família", você pode decidir que um parque é duas vezes mais importante que um museu. Comece com suas melhores hipóteses e faça iterações com base no feedback dos usuários.
Normalizar a pontuação: a consulta abaixo usa duas expressões de tabela comum (CTEs): a primeira calcula as contagens brutas como antes, e a segunda calcula as pontuações ponderadas. A instrução SELECT final realiza uma normalização min-max nas pontuações ponderadas. A coluna location da tabela de exemplo apartment_listings é gerada para ativar a visualização de dados em um mapa.
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;
Os resultados da consulta serão semelhantes aos mostrados abaixo. As duas últimas colunas são as pontuações normalizadas.
Entender a pontuação normalizada
É importante entender por que essa etapa final de normalização é tão valiosa.
As pontuações ponderadas brutas podem variar de 0 a um número potencialmente muito grande, dependendo da densidade urbana dos seus locais. Uma pontuação de 500 não faz sentido para um usuário sem contexto.
A normalização transforma esses números abstratos em um ranking relativo. Ao dimensionar os resultados de 0 a 10, a pontuação comunica claramente como cada local se compara aos outros no seu conjunto de dados específico:
- Uma pontuação de 10 é atribuída ao local com a maior pontuação bruta, marcando-o como a melhor opção no conjunto atual.
- Uma pontuação de 0 é atribuída ao local com a menor pontuação bruta, tornando-o o valor de referência para comparação. Isso não significa que o local não tenha comodidades, mas sim que ele é o menos adequado em relação às outras opções avaliadas.
- Todas as outras pontuações ficam proporcionalmente entre esses valores, oferecendo aos usuários uma maneira clara e intuitiva de comparar as opções rapidamente.
Opção 2: usar a API Gemini Developer
Como alternativa ao uso de uma fórmula matemática fixa no BigQuery, a API Gemini Developer oferece uma maneira eficiente de calcular pontuações de localização personalizadas e sutis.
Embora a opção 1 seja excelente para pontuações puramente quantitativas com base em contagens de comodidades, ela não pode considerar facilmente dados qualitativos. Ao usar o Gemini, você pode combinar os números da sua consulta do Places Insights com dados não estruturados, como a descrição textual do anúncio de apartamento (por exemplo, "Este lugar é adequado para famílias e a área é tranquila à noite") ou preferências específicas do perfil do usuário (por exemplo, "Esse usuário está reservando para uma família e prefere uma área tranquila em um local central"), para gerar uma pontuação mais detalhada.
Preparar os dados para o Gemini
Para usar esse método, transforme os resultados da agregação do BigQuery (da Etapa 2) em formato Markdown e combine com seus dados qualitativos, como um Listing Description.
Neste exemplo, temos duas fichas com características muito diferentes. Também incluímos um Target User Profile para informar ao Gemini para quem estamos avaliando essas respostas:
## 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.
Instruções do sistema
O Gemini precisa de instruções do sistema para saber como ponderar esses diferentes pontos de dados. Você pode informar explicitamente ao modelo a importância de comodidades específicas e instruí-lo a considerar o sentimento das descrições de texto.
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.
Resposta estruturada
Para garantir a confiabilidade ao integrar a IA ao seu aplicativo, não confie apenas em comandos para o formato de saída. Em vez disso, use o recurso de saída estruturada do Gemini. Ao fornecer um responseSchema, você garante que o modelo retorne uma matriz JSON limpa e analisável que corresponda aos requisitos exatos do sistema.
No nosso exemplo, podemos aplicar o seguinte esquema:
{
"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"
}
}
}
}
Exemplo de saída
Quando você envia o comando com o responseSchema definido, o Gemini retorna uma matriz JSON estruturada pronta para ser usada diretamente pelo seu aplicativo.
Observe na saída como o Gemini lida com os prós e contras. "The Downtowner" tem um número incrivelmente alto de parques, mas o Gemini identifica a descrição "barulhento nos fins de semana" como um grande ponto negativo para uma criança pequena. Enquanto isso, "Oásis suburbano" tem uma pontuação quase perfeita ao combinar excelente densidade de comodidades com recursos qualitativos aplicáveis, como "rua tranquila e arborizada".
[
{
"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
}
]
Esse método permite oferecer uma pontuação altamente personalizada, que parece inteligível e adaptada a cada usuário.
4. Visualizar suas pontuações em um mapa
O BigQuery Studio inclui uma visualização de mapa integrada para qualquer resultado de consulta que contenha uma coluna GEOGRAPHY. Como nossa consulta gera a coluna location, você pode visualizar suas pontuações imediatamente.
Ao clicar na guia Visualization, o mapa vai aparecer, e o menu suspenso Data Column controla a pontuação do local a ser visualizada. Neste exemplo, o
normalized_pet_score é visualizado no exemplo da opção 1. Observe que mais locais foram adicionados à tabela apartment_listings para este exemplo.
A visualização dos dados revela rapidamente os locais mais adequados para a pontuação criada, com círculos verdes mais escuros representando locais com um normalized_pet_score maior, neste caso. Para mais opções de visualização de dados do Places Insights, consulte Visualizar resultados da consulta.
Conclusão
Agora você tem uma metodologia poderosa e repetível para criar pontuações de local refinadas. Começando com seus locais, você criou uma única consulta SQL no BigQuery que encontra lugares próximos com ST_DWITHIN, filtra por atributos avançados, como good_for_children e allows_dogs, e agrega os resultados com COUNTIF. Ao aplicar ponderações personalizadas e normalizar o resultado, você gerou uma única pontuação fácil de usar que oferece insights profundos e úteis. Você pode aplicar esse padrão diretamente para transformar dados brutos de localização em uma vantagem competitiva significativa.
Próximas ações
Agora é sua vez de criar. Este tutorial fornece um modelo. Use os dados avançados disponíveis no esquema do Places Insights para criar as pontuações mais necessárias para seu caso de uso. Considere estas outras pontuações que você pode criar:
- "Pontuação da vida noturna": combine filtros para
primary_type(bar,night_club),price_levele horários de funcionamento até tarde da noite para encontrar as áreas mais vibrantes depois que escurece. - "Pontuação de fitness e bem-estar": conta
gyms,parksehealth_food_storesnas proximidades e filtra restaurantes comserves_vegetarian_foodpara pontuar locais para usuários preocupados com a saúde. - "Pontuação de sonho do viajante": encontre locais com alta densidade de lugares
transit_stationeparkingpróximos para ajudar usuários que valorizam o acesso ao transporte.
Colaboradores
Henrik Valve | Engenheiro de DevX