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

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 inúmeras opções. E se você pudesse facilitar isso para 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 localização dinâmicas e personalizadas, com base na densidade de lugares em uma área geográfica definida. A pontuação, um ranking numérico em relação aos critérios especificados, vai comunicar instantaneamente a adequação do local às necessidades.

Imagine que você está promovendo hotéis em uma cidade e quer destacar aqueles nas áreas turísticas mais atraentes criando uma pontuação boa para turistas. Use a API Places Aggregate para contar quantos tipos de lugares 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 lugares 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 próximos. 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 boa para turistas como o exemplo principal, mas sua pontuação pode ser criada para refletir os dados demográficos 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 (em inglês) para entender os detalhes técnicos e os parâmetros disponíveis.
• [Opcional] Documentação para desenvolvedores da API Gemini Developer (em inglês) 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.

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 de local personalizado de cinco locais pré-preenchidos.

Selecione os tipos de lugar relevantes

A primeira etapa para criar sua pontuação de local personalizada é decidir os tipos de lugar relevantes para seus clientes na Tabela A. Como estamos criando uma pontuação boa para turistas, selecionamos os seguintes tipos de lugares que os turistas vão querer ter 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. Para este exemplo, a escala de ponderação estará entre 0 e 1, da seguinte forma:

Chamar a API Places Aggregate

Agora que você tem uma lista de tipos de lugares de seu interesse, a próxima etapa é chamar a API Places Aggregate.

A API Places Aggregate exige um filtro de local. Para este exemplo, use circle, com o centro latLng sendo a localização 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 lugares com classificação mais baixa das contagens.

Teste variar as 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. Você também pode usar outro método 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 que você quer gerar uma pontuação personalizada. Por exemplo, ligue para o tipo de lugar do restaurante de 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 este para cada local:

Gerar a pontuação de local personalizada

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 um algoritmo local ou a API Gemini Developer.

Opção 1: usar um algoritmo

A primeira opção que vamos abordar é usar um algoritmo local para gerar uma pontuação com 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
    }
    

Para gerar uma pontuação com base nas contagens e ponderações, multiplique o itemCounts pelo typeWeights e adicione 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, a saída dessa etapa é: 78,3.

Agora você pode usar a normalização logarítmica para gerar a pontuação final desse local em uma escala entre 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));

Neste 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 personalizado para todos os locais. Basta fornecer os dados de contagem e ponderação com instruções do sistema para todas as unidades do hotel.

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

• Descrições textuais de cada local do 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, o que resulta em uma pontuação mais sofisticada e relevante do que uma abordagem puramente matemática.

Ao usar a API Gemini Developer, além da tabela de tipo de lugar e ponderação acima, você pode ter dados de descrição para cada local que se parecem com isto:

Essas descrições qualitativas, junto com 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 é esperado gerar uma pontuação para cada local, com base nos pontos de dados fornecidos. Uma instrução de sistema de exemplo para isso pode ser a 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 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 quando consultarmos com código. Para isso, podemos adicionar uma instrução de saída estruturada à 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 pede que o Gemini gere 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 local 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 filtragem de pesquisa. Por exemplo, "mostre lugares com uma pontuação alta de bom para turistas". Assim, seus clientes podem tomar decisões com base em dados ao fazer uma reserva.

Conclusão

Usar pontuações de locais personalizados pode ser uma ferramenta eficiente para dar aos usuários uma visão geral da adequação de uma área. Este documento mostrou como gerar pontuações de local personalizadas para vários locais usando cinco tipos de lugares separados. Essa implementação pode ser modificada para atender às suas necessidades, e tipos de lugares semelhantes podem ser combinados em uma 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 e ajudar seus clientes a tomar decisões fundamentadas com base na localização.

Colaboradores

Henrik Valve | Engenheiro de DevX