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

Цель

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

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

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

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

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

Предварительные условия

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

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

Демо

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

Выберите подходящие типы мест

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

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

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

Агрегированный API мест вызова

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

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

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

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

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

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. Используйте API разработчика Gemini.

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

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

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

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

Отобразить счет

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

Заключение

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

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

Авторы

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