Objetivo
Encontrar o local ideal, seja um hotel para as próximas férias ou um apartamento para a família, geralmente envolve um processo frustrante e demorado de comparação de várias opções. E se você pudesse facilitar isso para os usuários fornecendo uma métrica personalizada que revela a adequação de um hotel para turistas ou classifica os anúncios de apartamentos com base na adequação para famílias, transformando uma tarefa tediosa em uma decisão simples?
Neste documento, mostramos como usar a API Places Aggregate para gerar pontuações de localização dinâmicas e personalizadas com base na densidade de lugares em uma área geográfica definida. A pontuação, uma classificação numérica em relação aos critérios especificados, vai comunicar instantaneamente se o local é adequado para as necessidades deles.
Imagine que você está promovendo hotéis em uma cidade e quer destacar aqueles nas áreas turísticas mais atraentes criando uma pontuação de bom para turistas. Use a API Places Aggregate para contar quantos tipos de lugar relevantes estão perto de cada hotel. Por exemplo, você sabe que seus clientes valorizam hotéis em locais próximos a:
- Restaurantes e cafés
- Parques e museus
- Lojas de roupas
Ao aplicar ponderações de importância às contagens desses tipos de lugar selecionados, é possível calcular uma pontuação geral para cada local de hotel. A pontuação reflete a adequação geral do local, com base nos lugares por perto. As ponderações atribuídas a cada tipo de lugar precisam estar alinhadas ao seu caso de uso específico e ao que é importante para seu público-alvo. Este documento usa uma pontuação de bom para turistas como exemplo principal, mas sua pontuação pode ser criada para refletir as informações demográficas e as necessidades dos usuários.
Pré-requisitos
Antes de ler este documento, recomendamos que você se familiarize com a seguinte documentação:
- Documentação para desenvolvedores da API Places Aggregate para entender os detalhes técnicos e os parâmetros disponíveis.
- [Opcional] Documentação para desenvolvedores da API Gemini Developer para entender como chamar o Gemini usando uma API. Ela é usada neste documento como uma opção para gerar a pontuação de local personalizada.
Selecione os tipos de lugar relevantes
A primeira etapa para criar sua pontuação de local personalizada é decidir os tipos de lugar da Tabela A que são relevantes para seus clientes. Como estamos criando uma pontuação de bom para turistas, selecionamos os seguintes tipos de lugar que os turistas vão querer por perto durante a estadia:
- restaurante
- parque
- clothing_store
- museu
- coffee_shop
Em seguida, atribua uma ponderação a cada um desses tipos de lugar, refletindo a importância relativa deles na pontuação final. As ponderações devem ser determinadas com base no que é mais importante para seu caso de uso e nas preferências do usuário. Neste exemplo, a escala de ponderação será entre 0 e 1, da seguinte forma:
Tipo de lugar |
Ponderação |
restaurante |
0,8 |
parque |
0,6 |
clothing_store |
0,3 |
museu |
0,2 |
coffee_shop |
0,5 |
Chamar a API Places Aggregate
Agora que você tem uma lista de tipos de lugar de seu interesse, a próxima etapa é chamar a API Places Aggregate.
A API Places Aggregate exige um filtro de local. Neste exemplo, use circle,
com o centro latLng sendo o local do seu hotel e um radius de
500 m. Defina também ratingFilter para retornar lugares com uma classificação entre 3,8 e 5, excluindo os lugares com classificações mais baixas das contagens.
Teste diferentes configurações do filtro de local para seu caso de uso específico. Por exemplo, para capturar lugares em um raio maior da latitude e longitude centrais, aumente o valor do raio. Como alternativa, use um método diferente para definir a área de pesquisa, como Região ou Área personalizada.
Conheça a seção de filtro de local da documentação da API Places Aggregate para saber mais sobre as opções disponíveis.
Chame a API Places Aggregate para cada tipo de lugar e local em que você quer gerar uma pontuação personalizada. Por exemplo, chame o tipo de lugar "restaurante" para um dos seus hotéis:
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
}
}
}'
Depois que todas as chamadas para a API forem concluídas, você terá dados como estes para cada local:
Tipo de lugar |
Ponderação |
Contagem |
restaurante |
0,8 |
56 |
parque |
0,6 |
3 |
clothing_store |
0,3 |
32 |
museu |
0,2 |
8 |
coffee_shop |
0,5 |
41 |
Gerar a pontuação de local personalizada
Agora que você tem a contagem de lugares e a ponderação para cada tipo de lugar em cada local, é possível gerar a pontuação de local personalizada. Nesta seção, vamos discutir duas opções: usar um algoritmo local ou a API Gemini Developer.
Opção 1: usar um algoritmo
A primeira opção que vamos abordar é o uso de um algoritmo local para gerar uma pontuação usando as ponderações e contagens de cada tipo de lugar. Normalize essa pontuação em uma escala de 0 a 5, em que valores mais altos indicam uma área mais atraente com base nos seus critérios. Para este exemplo, gere dois objetos JavaScript com base nos dados acima:
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 } |
Gere uma pontuação com base nas contagens e ponderações multiplicando o itemCounts
pelo typeWeights e adicionando os resultados a um weightedCount geral:
let weightedCount = 0;
for (const itemType in itemCounts) {
weightedCount += itemCounts[itemType] * typeWeights[itemType];
}
weightedCount = weightedCount.toFixed(2);
Neste exemplo, o resultado dessa etapa é: 78,3.
Agora você pode usar a normalização logarítmica para gerar a pontuação final desse local em uma escala de 0 a 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));
Neste exemplo, a pontuação final é: 4,36 (arredondada para duas casas decimais).
Opção 2: usar a API Gemini Developer
Como alternativa ao uso de um algoritmo local, a API Gemini Developer oferece uma maneira eficiente de calcular a pontuação de local personalizada para todos os locais. Basta fornecer os dados de contagem e ponderação com instruções do sistema para todos os locais do hotel.
Esse método é especialmente útil se você tiver informações detalhadas que gostaria de incluir no cálculo, como:
- Descrições de texto para cada local de hotel, por exemplo: "Este local é adequado para famílias, e a área é tranquila à noite".
- Informações sobre o usuário, como: "Este usuário está fazendo uma reserva para uma família e prefere uma área tranquila em um local central".
A API Gemini Developer pode entender e considerar esses dados qualitativos, gerando uma pontuação mais sofisticada e relevante do que uma abordagem puramente matemática.
Ao usar a API Gemini Developer, além do tipo de lugar e da tabela de ponderação acima, você pode ter dados de descrição para cada local, como:
Local |
Descrição |
Localização central perto de museus, tranquila à noite e adequada para famílias. |
|
Localização central perto de bares e restaurantes. Barulhento e movimentado à noite, bom para grupos. |
|
Local residencial longe do centro da cidade. |
|
Localização central perto do rio. Silencioso à noite e adequado para famílias. |
|
Local residencial longe do centro da cidade. |
Essas descrições qualitativas, junto com as informações ou preferências do usuário, podem ser incluídas no comando para o Gemini.
Instruções do sistema
O Gemini precisa de instruções, além dos dados brutos, para saber que precisa gerar uma pontuação para cada local com base nos pontos de dados fornecidos. Veja um exemplo de instrução do sistema para fazer isso:
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
As instruções do sistema acima informam ao Gemini quais dados esperar e qual é a saída esperada do modelo de IA. Elas também solicitam a saída em JSON.
Resposta estruturada
Embora tenhamos pedido ao Gemini para gerar o resultado em JSON, precisamos ser mais específicos sobre a estrutura da saída para saber o que esperar ao consultá-la com código. Para isso, podemos adicionar uma instrução de saída estruturada extra à solicitação usando o campo responseSchema na API Gemini. Isso usa um objeto de esquema OpenAPI para restringir a saída do modelo.
Exemplo:
{
"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"
]
}
}
Neste exemplo, o Gemini precisa gerar uma matriz JavaScript com o seguinte:
- Latitude e longitude do local
- A pontuação de local personalizado
Usando as instruções do sistema e a saída estruturada acima, a resposta do
Gemini para um local seria assim, com score sendo a pontuação personalizada
do local:
[
{
"location": {
"latitude": 51.51611,
"longitude": -0.12726
},
"score": "4.13"
}
]
Mostrar a pontuação
Depois de gerar a pontuação de localização personalizada para cada local usando um dos métodos descritos, ela pode ser exibida ao lado dos detalhes do hotel ou usada como uma opção de filtro de pesquisa. Por exemplo, "mostre lugares com uma pontuação alta de bom para turistas". Isso vai permitir que seus clientes tomem decisões com base em dados ao fazer reservas.
Conclusão
Usar pontuações de locais personalizados pode ser uma ferramenta poderosa para dar aos usuários uma visão geral rápida da adequação de uma área. Este documento demonstrou como gerar pontuações de local personalizadas para vários locais usando cinco tipos de lugar diferentes. Essa implementação pode ser modificada para atender às suas necessidades, e tipos de lugar semelhantes podem ser combinados em uma única solicitação para retornar a contagem agregada desses tipos e fornecer à sua solução personalizada de pontuação de local.
Teste a API Places Aggregate hoje mesmo para gerar pontuações de localização úteis que ajudam seus clientes a tomar decisões bem fundamentadas com base na localização.
Colaboradores
Henrik Valve | Engenheiro de DevX