Используйте Places Aggregate API для создания собственной оценки местоположения. Используйте Places Aggregate API для создания собственной оценки местоположения. Используйте Places Aggregate API для создания собственной оценки местоположения. Используйте Places Aggregate API для создания собственной оценки местоположения.

Цель

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

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

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

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

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

Предпосылки

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

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

Демо

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

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

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

• ресторан
• парк
• магазин_одежды
• музей
• кофейный магазин

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

API агрегации мест вызовов

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

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

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

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

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

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 у вас будут данные для каждого местоположения, которые выглядят следующим образом:

Сгенерировать оценку местоположения

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

Вариант 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: использование API разработчика Gemini

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

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

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

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

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

Эти качественные описания вместе с любой пользовательской информацией или предпочтениями можно включить в ваш запрос для 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 в API Gemini. В этом случае для ограничения вывода модели используется объект схемы 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"
  }
]

Показать счет

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

Заключение

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

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

Авторы

Хенрик Валв | Инженер DevX