امتیازهای مکان سفارشی Places Aggregate

هدف اصلی

پیدا کردن مکان ایده‌آل، چه هتلی برای تعطیلات پیش‌رو باشد چه آپارتمانی مناسب خانواده، اغلب فرایندی خسته‌کننده و زمان‌بر است که شامل مقایسه گزینه‌های متعدد می‌شود. چه می‌شد اگر می‌توانستید با ارائه سنجه‌ای سفارشی‌شده که مناسب بودن هتل را برای گردشگران نشان می‌دهد یا فهرست‌های آپارتمان را براساس مناسب بودن برای خانواده رتبه‌بندی می‌کند، این کار را برای کاربران خود آسان‌تر کنید و کاری خسته‌کننده را به تصمیمی بی‌دردسر تبدیل کنید.

این سند نحوه استفاده از Places Aggregate API را برای تولید امتیازهای مکان سفارشی و پویا براساس تراکم مکان‌ها در یک منطقه جغرافیایی تعریف‌شده شرح می‌دهد. امتیاز، که رتبه‌بندی عددی براساس معیارهای مشخص‌شده شما است، فوراً نشان می‌دهد که مکان چقدر برای نیازهای آن‌ها مناسب است.

سناریویی را درنظر بگیرید که در آن هتل‌های شهری را تبلیغ می‌کنید و می‌خواهید با ایجاد امتیاز مناسب برای گردشگران، هتل‌هایی را که در جذاب‌ترین مناطق گردشگری قرار دارند برجسته کنید. از Places Aggregate API برای شمارش تعداد انواع مکان مرتبط در نزدیکی هر هتل استفاده کنید. برای مثال، می‌دانید که مشتریانتان برای هتل‌هایی ارزش قائل هستند که در مکان‌هایی نزدیک به موارد زیر قرار دارند:

• رستوران‌ها و قهوه‌سراها
• پارک‌ها و موزه‌ها
• لباس‌فروشی

با اعمال وزن‌های اهمیت به تعداد این نوع مکان‌های انتخاب‌شده، می‌توانید امتیاز کلی برای هر مکان هتل محاسبه کنید. این امتیاز نشان‌دهنده مناسب بودن کلی مکان براساس جاهای اطراف است. وزن‌های اختصاص‌داده‌شده به هر نوع مکان باید با مورد استفاده خاص شما و آنچه برای مخاطب هدف شما مهم است همسو باشد. این سند از امتیاز مناسب برای گردشگران به‌عنوان نمونه اصلی استفاده می‌کند، اما امتیاز شما می‌تواند به‌گونه‌ای ساخته شود که جمعیت‌شناسی و نیازهای کاربرانتان را منعکس کند.

پیش‌نیازها

قبل‌از خواندن این سند، توصیه می‌شود با اسناد زیر آشنا شوید:

• برای درک جزئیات فنی و پارامترهای دردسترس، به مستندات توسعه‌دهنده Places Aggregate API مراجعه کنید.
• [اختیاری] مستندات توسعه‌دهنده Gemini Developer API برای درک نحوه فراخوانی Gemini بااستفاده از API و استفاده از آن در این سند به‌عنوان گزینه‌ای برای تولید امتیاز مکان سفارشی.

انتخاب انواع مکان‌های مرتبط

اولین قدم برای ساختن امتیاز مکان سفارشی این است که درباره انواع مکان‌هایی که به مشتریانتان مربوط است از جدول الف تصمیم بگیرید. ازآنجایی‌که درحال ایجاد امتیاز مناسب برای گردشگران هستیم، انواع مکان‌های زیر را انتخاب کرده‌ایم که گردشگران مایلند درطول اقامتشان در نزدیکی آن‌ها باشند:

• رستوران
• پارک
• clothing_store
• موزه
• coffee_shop

سپس، به هریک از این انواع مکان وزنی اختصاص دهید که اهمیت نسبی آن را در امتیاز نهایی نشان دهد. وزن‌دهی باید براساس آنچه برای مورد استفاده شما و اولویت‌های کاربرتان مهم‌تر است تعیین شود. برای این مثال، مقیاس وزنی بین ۰ و ۱ خواهد بود، به‌صورت زیر:

فراخوانی Places Aggregate API

اکنون که فهرستی از انواع مکان‌های موردعلاقه‌تان دارید، مرحله بعدی فراخوانی Places Aggregate API است.

Places Aggregate API به فیلتر مکان نیاز دارد. برای این مثال، از circle استفاده کنید، با مرکز latLng که مکان هتل شما است، و radius ۵۰۰ متری. همچنین ratingFilter را تنظیم کنید تا مکان‌هایی با رده‌بندی بین ۳٫۸ و ۵ را برگرداند و مکان‌های با رده‌بندی پایین‌تر را از شمارش مستثنی کند.

تنظیمات فیلتر مکان را برای مورد استفاده خاص خودتان تغییر دهید و آزمایش کنید. برای مثال، شاید بخواهید با افزایش مقدار شعاع، مکان‌های موجود در شعاع وسیع‌تری از طول و عرض جغرافیایی مرکزتان را ضبط کنید. یا شاید بخواهید از روش دیگری برای تنظیم منطقه جستجو استفاده کنید، مثلاً منطقه یا منطقه سفارشی.

برای آشنایی با گزینه‌های دردسترس، با بخش فیلتر مکان در اسناد 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 بررسی خواهیم کرد.

گزینه ۱: استفاده از الگوریتم

اولین گزینه‌ای که پوشش خواهیم داد استفاده از الگوریتم محلی برای تولید امتیاز بااستفاده از وزن‌ها و تعداد برای هر «نوع مکان» است. این امتیاز را به مقیاس ۰ تا ۵ نرمال‌سازی کنید، که در آن مقادیر بالاتر نشان‌دهنده منطقه‌ای جذاب‌تر براساس معیارهای شما است. برای این مثال، دو شیء جاوا اسکریپت از داده‌های بالا تولید کنید:

    {
      "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 است.

اکنون می‌توانید از نرمال‌سازی لگاریتمی برای تولید امتیاز نهایی این مکان در مقیاس بین ۰ تا ۵ استفاده کنید:

if (weightedCount === 0) {
   normalizedScore = 0;
} else {
   normalizedScore = Math.log(weightedCount + 1);
}

// Clamp between 0 and 5
normalizedScore = Math.max(0, Math.min(5, normalizedScore));

برای این مثال، برونداد امتیاز نهایی عبارت است از: ۴٫۳۶ (گردشده تا دو رقم اعشار).

گزینه ۲: استفاده از 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 می‌خواهد که یک آرایه جاوا اسکریپت با موارد زیر خروجی دهد:

• طول و عرض جغرافیایی مکان
• امتیاز مکان سفارشی

بااستفاده از دستورالعمل‌های سیستم بالا و خروجی ساختاریافته، پاسخ Gemini برای یک مکان به‌صورت زیر خواهد بود و score امتیاز سفارشی مکان است:

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

نمایش دادن امتیاز

پس‌از اینکه امتیاز مکان سفارشی را برای هر مکان بااستفاده از یکی از روش‌های شرح‌داده‌شده تولید کردید، این امتیاز می‌تواند درکنار جزئیات هتل شما نمایش داده شود یا به‌عنوان گزینه فیلتر کردن جستجو استفاده شود. برای مثال، «مکان‌هایی را که امتیاز بالایی در مناسب برای گردشگران دارند به من نشان بده». این کار به مشتریانتان امکان می‌دهد هنگام رزرو کردن، تصمیم‌های مبتنی بر داده بگیرند.

نتیجه‌گیری

استفاده از امتیازهای مکان‌های سفارشی می‌تواند ابزاری قدرتمند برای ارائه نمای کلی از مناسب بودن یک منطقه به کاربران شما باشد. این سند نحوه تولید امتیازهای مکان سفارشی برای مکان‌های مختلف را بااستفاده از پنج نوع مکان مجزا نشان داد. این پیاده‌سازی را می‌توان برای مطابقت با نیازهای شما تغییر داد و انواع مکان‌های مشابه را می‌توان در یک درخواست ترکیب کرد تا تعداد تجمیعی آن انواع را برگرداند و به راه‌حل امتیازدهی مکان سفارشی شما ارائه دهد.

Places Aggregate API را همین امروز امتحان کنید تا امتیازهای مکان مفیدی تولید کنید و به مشتریانتان کمک کنید تصمیم‌های آگاهانه‌ای براساس مکان بگیرند!

همیاران

هنریک والو | مهندس DevX