Оценки пользовательских местоположений в Places Aggregate

Цель

Поиск идеального места, будь то отель для предстоящего отпуска или апартаменты для всей семьи, часто включает в себя утомительный и трудоемкий процесс сравнения многочисленных вариантов. Что, если бы вы могли помочь своим пользователям, предоставив им специальный показатель, который показывает, насколько отель подходит для туристов, или ранжирует объявления о квартирах по их удобству для семей, превращая утомительную рутину в легкое решение?

В этом документе рассказывается, как использовать Places Aggregate API для динамического создания пользовательских оценок местоположений на основе плотности мест в определенной географической области. Оценка – числовой рейтинг, основанный на указанных вами критериях, – сразу покажет, насколько место подходит для их нужд.

Предположим, вы продвигаете гостиницы в определенном городе и хотите выделить те, которые находятся в самых привлекательных туристических районах, создав оценку привлекательности для туристов. Используйте Places Aggregate API, чтобы подсчитать, сколько типов мест находится рядом с каждым отелем. Например, вы знаете, что ваши клиенты предпочитают отели, расположенные рядом с:

• Рестораны и кафе
• Парки и музеи
• Магазины одежды

Применив весовые коэффициенты важности к количеству выбранных типов мест, вы можете рассчитать общую оценку для каждого местоположения отеля. Оценка отражает общую пригодность местоположения на основе мест рядом. Веса, присвоенные каждому типу места, должны соответствовать вашему конкретному варианту использования и тому, что важно для вашей целевой аудитории. В этом документе в качестве основного примера будет использоваться оценка Подходит для туристов, но вы можете создать оценку, отражающую демографические характеристики и потребности ваших пользователей.

Требования

Прежде чем приступить к изучению этого документа, рекомендуем ознакомиться со следующими материалами:

• Документация для разработчиков по Places Aggregate API, в которой приведены технические сведения и доступные параметры.
• [Необязательно] Документация для разработчиков по Gemini Developer API, которая поможет понять, как вызывать Gemini с помощью API. В этом документе Gemini Developer API используется как один из вариантов для создания пользовательской оценки местоположения.

Выбор типов мест

Сначала выберите из таблицы A типы мест, которые могут быть интересны вашим клиентам. Поскольку мы создаем оценку Подходит для туристов, мы выбрали следующие типы мест, рядом с которыми туристы захотят находиться во время своего пребывания:

• ресторан
• парк
• clothing_store
• музей
• coffee_shop

Затем присвойте каждому из этих типов мест вес, отражающий его относительную важность в итоговой оценке. Весовые коэффициенты следует определять на основе того, что наиболее важно для вашего варианта использования и предпочтений вашего пользователя. В нашем примере шкала весов будет от 0 до 1:

Вызов Places Aggregate API

Теперь, когда у вас есть список интересующих вас типов мест, следующим шагом будет вызов Places Aggregate API.

Для Places Aggregate API требуется фильтр местоположения. В этом примере используется метод circle, в котором центр latLng – это местоположение гостиницы, а radius – 500 м. Также настройте ratingFilter так, чтобы возвращались места с рейтингом от 3,8 до 5, исключая места с более низким рейтингом.

Поэкспериментируйте с настройками фильтра местоположений, чтобы найти оптимальный вариант для вашего случая. Например, вы можете увеличить значение радиуса, чтобы получить места в более широком радиусе от центральной широты и долготы. Вы также можете задать область поиска другим способом, например выбрать Регион или Своя область.

Ознакомьтесь с разделом Фильтр местоположений в документации по Places Aggregate API, чтобы узнать о доступных вариантах.

Вызовите Places Aggregate API для каждого типа места и местоположения, для которых вы хотите сгенерировать собственную оценку. Например, вызовите тип места "ресторан" для одного из ваших отелей:

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
        }
    }
}'

После выполнения всех вызовов API у вас будут данные, которые для каждого местоположения выглядят следующим образом:

Как создать специальную оценку местоположения

Теперь, когда у вас есть количество мест и взвешивание для каждого типа места для каждого местоположения, вы можете сгенерировать оценку местоположения. В этом разделе мы обсудим два варианта: использование локального алгоритма и использование Gemini Developer API.

Вариант 1. Использование алгоритма

Первый вариант, который мы рассмотрим, – это использование локального алгоритма для генерации оценки с использованием весов и количества для каждого типа места. Нормализуйте эту оценку по шкале от 0 до 5, где более высокие значения указывают на более привлекательную область на основе ваших критериев. В этом примере создайте два объекта JavaScript из приведенных выше данных:

    {
      "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
    }
    

Рассчитайте оценку на основе количества и веса, умножив itemCounts на typeWeights и добавив результаты к общему weightedCount:

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

В нашем примере результатом этого шага будет 78, 3.

Теперь вы можете использовать логарифмическую нормализацию, чтобы получить итоговую оценку для этого местоположения по шкале от 0 до 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));

В нашем примере итоговая оценка равна 4, 36 (округлено до двух знаков после запятой).

Вариант 2. Использовать Gemini Developer API

В качестве альтернативы локальному алгоритму Gemini Developer API предлагает мощный способ вычисления пользовательской оценки местоположения для всех местоположений. Просто предоставьте данные о количестве и весе вместе с системными инструкциями для всех ваших отелей.

Этот метод особенно полезен, если вы хотите включить в расчет дополнительную информацию, например:

• Текстовые описания для каждого отеля, например: "Этот отель подходит для семейного отдыха, а по ночам здесь тихо".
• Информация о пользователе, например: "Этот пользователь бронирует номер для семьи и предпочитает тихий район в центре города".

Gemini Developer API может понимать и учитывать эти качественные данные, что позволяет получить более сложную и релевантную оценку, выходящую за рамки чисто математического подхода.

Используя Gemini Developer API, в дополнение к типу места и таблице весовых коэффициентов выше, вы можете получить данные описания для каждого местоположения, которые выглядят следующим образом:

Эти качественные описания вместе с любой информацией о пользователе или его предпочтениях можно включить в запрос к Gemini.

Системные инструкции

Gemini нужны инструкции и необработанные данные, чтобы понять, что от него требуется сгенерировать оценку для каждого местоположения на основе предоставленных данных. Пример системной инструкции для достижения этой цели может быть следующим:

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

Приведенные выше системные инструкции позволяют Gemini узнать, какие данные ожидать и каков ожидаемый результат работы ИИ-модели. Он также запрашивает вывод в формате JSON.

Структурированные выходные данные

Хотя мы попросили Gemini вывести результат в формате JSON, нам нужно более точно указать структуру выходных данных, чтобы мы знали, чего ожидать при запросе с помощью кода. Для этого мы можем добавить в запрос дополнительную инструкцию по структурированному выводу, используя поле responseSchema в Gemini API. Для ограничения выходных данных модели используется объект схемы OpenAPI.

Пример:

{
  "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"
    ]
  }
}

В этом примере Gemini просят вывести массив JavaScript со следующими данными:

• Широта и долгота местоположения
• Оценка собственного местоположения

При использовании приведенных выше системных инструкций и структурированных выходных данных ответ Gemini для одного местоположения будет выглядеть следующим образом, где score – это оценка местоположения:

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

Показывать оценку

После того как вы сгенерируете собственную оценку местоположения для каждого отеля, используя один из описанных методов, ее можно будет показывать вместе с информацией об отеле или использовать в качестве фильтра поиска. Например, "покажи мне места с высоким рейтингом подходит для туристов". Это позволит вашим клиентам принимать решения на основе данных при бронировании.

Заключение

Использование пользовательских оценок местоположений может быть мощным инструментом, позволяющим пользователям сразу получить представление о пригодности того или иного района. В этом документе показано, как генерировать пользовательские оценки местоположений для различных местоположений, используя пять отдельных типов мест. Эту реализацию можно изменить в соответствии с вашими потребностями, а похожие типы мест можно объединить в один запрос, чтобы получить агрегированное количество этих типов и передать его в ваше решение для оценки местоположения.

Попробуйте Places Aggregate API уже сегодня, чтобы генерировать полезные оценки мест и помогать клиентам принимать взвешенные решения на основе местоположения.

Авторы

Хенрик Вальве (Henrik Valve) | инженер DevX