Usar a API Places Aggregate para criar uma pontuação de local personalizada

Objetivo

Encontrar o local ideal, seja um hotel para suas próximas férias ou um apartamento para famílias, geralmente envolve um processo frustrante e demorado de comparação de várias opções. E se você pudesse facilitar a vida dos seus 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 fácil?

Este documento descreve como usar a API Places Aggregate para gerar pontuações de local dinâmicas e personalizadas com base na densidade de lugares em uma área geográfica definida. A pontuação, uma classificação numérica com base nos critérios especificados, vai comunicar instantaneamente como o local é adequado para as necessidades.

Considere um cenário em que você está promovendo hotéis em uma cidade e quer destacar os que estão nas áreas turísticas mais atraentes criando uma pontuação boa 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 que estão próximos a alguns dos seguintes:

• Restaurantes e cafés
• Parques e museus
• Lojas de roupas

Ao aplicar pesos de importância às contagens desses tipos de lugar selecionados, é possível calcular uma pontuação geral para cada local do hotel. A pontuação reflete a adequação geral do local com base nos lugares próximos. Os pesos atribuídos a cada tipo de lugar precisam estar alinhados ao seu caso de uso específico e ao que é importante para seu público-alvo. Este documento vai usar uma pontuação boa para turistas como exemplo principal, mas sua pontuação pode ser criada para refletir os grupos demográficos e as necessidades do usuário.

Pré-requisitos

Antes de ler este documento, recomendamos que você conheça a seguinte documentação:

• Consulte a documentação para desenvolvedores da API Places Aggregate para entender os detalhes técnicos e os parâmetros disponíveis.
• [Opcional] Documentação da API para desenvolvedores do Gemini para entender como chamar o Gemini usando uma API e é usada neste documento como uma opção para gerar a pontuação de local personalizada.

Demonstração

Esta demonstração mostra um exemplo da pontuação de local personalizada em ação. Escolha uma cidade no menu suspenso e clique no botão Calcular pontuação personalizada para mostrar a pontuação do local personalizado para cinco locais predefinidos.

Selecionar tipos de lugar relevantes

A primeira etapa para criar a pontuação de local personalizada é decidir os tipos de lugar que são relevantes para seus clientes na Tabela A. Como estamos criando uma pontuação boa para turistas, selecionamos os seguintes tipos de lugar que os turistas vão querer visitar 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 precisam 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, conforme abaixo:

Chamar a API Places Aggregate

Agora que você tem uma lista de tipos de lugar que lhe interessam, a próxima etapa é chamar a API Places Aggregate.

A API Places Aggregate requer um filtro de local. Para este exemplo, use circle, com o latLng central sendo o local do seu hotel e um radius de 500 m. Defina também o ratingFilter para retornar lugares com uma classificação entre 3,8 e 5, excluindo os lugares com classificação mais baixa das contagens.

Teste diferentes configurações do filtro de local para seu caso de uso específico. Por exemplo, você pode capturar lugares em um raio maior da latitude e longitude do centro aumentando 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 Aggregate Places para saber mais sobre as opções disponíveis.

Chame a API Places Aggregate para cada tipo e local de lugar para o qual você quer gerar uma pontuação personalizada. Por exemplo, chame o tipo de lugar do 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 semelhantes a estes para cada local:

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 personalizada. Vamos discutir duas opções nesta seção, usando um algoritmo local ou a API Gemini para desenvolvedores.

Opção 1: usar um algoritmo

A primeira opção que vamos abordar é usar 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:

    {
      "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 as contagens e ponderações multiplicando o itemCounts pelo typeWeights e adicionando os resultados a uma weightedCount geral:

let weightedCount = 0;
for (const itemType in itemCounts) {
  weightedCount += itemCounts[itemType] * typeWeights[itemType];
}
weightedCount = weightedCount.toFixed(2);

Para este exemplo, a saída desta 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));

Para este exemplo, a saída da 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 seu hotel.

Esse método é especialmente útil se você tiver informações sutis que gostaria de incluir no cálculo, como:

• Descrições de texto para cada local do hotel, por exemplo: "Este local é adequado para famílias e a área é tranquila à noite".
• Informações sobre o usuário, como: "Esse 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, resultando em 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 que se parece com este:

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, junto com os dados brutos, para saber que ele precisa gerar uma pontuação para cada local com base nos pontos de dados fornecidos. Um exemplo de instrução do sistema para fazer isso pode ser o seguinte:

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 permitem que o Gemini saiba quais dados esperar e qual é a saída esperada do modelo de IA. Ele também solicita a saída em JSON.

Resposta estruturada

Embora tenhamos pedido para que o Gemini mostre o resultado em JSON, precisamos ser mais específicos sobre a estrutura da saída para sabermos o que esperar quando a consultarmos com código. Para isso, podemos adicionar uma instrução de saída estruturada adicional à solicitação usando o campo responseSchema na API Gemini. Isso usa um objeto de esquema da 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"
    ]
  }
}

Este exemplo solicita que o Gemini gere uma matriz JavaScript com o seguinte:

• Latitude e longitude do local
• A pontuação do local personalizado

Usando as instruções do sistema e a saída estruturada acima, a resposta do Gemini para um local será assim, com score sendo a pontuação de localização personalizada:

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

Mostrar a pontuação

Depois de gerar a pontuação do local personalizado para cada local usando um dos métodos descritos, ela pode ser exibida com os detalhes do seu 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 permite que seus clientes tomem decisões com base em dados ao fazer reservas.

Conclusão

Usar as pontuações de locais personalizadas pode ser uma ferramenta poderosa para mostrar aos usuários uma visão geral 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 solicitação para retornar a contagem agregada desses tipos e fornecer à solução de pontuação de local personalizada.

Teste a API Places Aggregate hoje mesmo para gerar pontuações de localização úteis e ajudar seus clientes a tomar decisões bem informadas com base na localização.

Colaboradores

Henrik Valve | Engenheiro do DevX