استفاده از Places Aggregate API برای ایجاد امتیاز موقعیت مکانی سفارشی، استفاده از Places Aggregate API برای ایجاد امتیاز موقعیت مکانی سفارشی، استفاده از Places Aggregate API برای ایجاد امتیاز موقعیت مکانی سفارشی، استفاده از Places Aggregate API برای ایجاد امتیاز موقعیت مکانی سفارشی

هدف

تصویر

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

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

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

  • رستوران ها و کافی شاپ ها
  • پارک ها و موزه ها
  • فروشگاه های پوشاک

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

پیش نیازها

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

نسخه ی نمایشی

این نسخه نمایشی نمونه ای از امتیاز موقعیت مکانی سفارشی را در عمل نشان می دهد. یک شهر را از منوی کشویی انتخاب کنید و روی دکمه محاسبه امتیاز سفارشی کلیک کنید تا امتیاز موقعیت مکانی سفارشی برای پنج مکان از پیش پرجمعیت نمایش داده شود.

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

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

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

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

نوع مکان

وزن دهی

رستوران

0.8

پارک

0.6

لباس_فروشی

0.3

موزه

0.2

کافی شاپ

0.5

Call Places Aggregate API

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

Places Aggregate API به فیلتر مکان نیاز دارد. برای این مثال از circle استفاده کنید، با latLng وسط مکان هتل شما، و radius 500 متر. همچنین ratingFilter طوری تنظیم کنید که مکان هایی با رتبه بندی بین 3.8 تا 5 را بازگرداند، به استثنای مکان های دارای رتبه پایین تر از شمارش ها.

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

با بخش فیلتر موقعیت مکانی مستندات Places Aggregate API آشنا شوید تا در مورد گزینه های موجود در دسترس خود بیاموزید.

Call Places Aggregate API برای هر نوع مکان و مکانی که می خواهید امتیاز سفارشی برای آن ایجاد کنید. برای مثال، برای رستوران 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، داده‌هایی برای هر مکان به شکل زیر در اختیار دارید:

نوع مکان

وزن دهی

بشمار

رستوران

0.8

56

پارک

0.6

3

لباس_فروشی

0.3

32

موزه

0.2

8

کافی شاپ

0.5

41

امتیاز موقعیت مکانی سفارشی را ایجاد کنید

اکنون تعداد مکان ها و وزن برای هر نوع مکان برای هر مکان را دارید، اکنون می توانید امتیاز مکان سفارشی را ایجاد کنید. ما در این بخش دو گزینه را مورد بحث قرار خواهیم داد، با استفاده از یک الگوریتم محلی یا استفاده از Gemini Developer API .

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

اولین گزینه ای که پوشش خواهیم داد استفاده از یک الگوریتم محلی برای ایجاد امتیاز با استفاده از وزن و شمارش برای هر نوع مکان است. این امتیاز را به یک مقیاس 0 تا 5 عادی کنید، جایی که مقادیر بالاتر بر اساس معیارهای شما منطقه جذاب تری را نشان می دهد. برای این مثال، دو شی جاوا اسکریپت را از داده های بالا ایجاد کنید:

تعداد آیتم ها

نوع وزن 

    {
      "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، علاوه بر نوع مکان و جدول وزنی بالا، می‌توانید داده‌های توصیفی برای هر مکان به شکل زیر داشته باشید:

مکان

توضیحات

51.49884, -0.17978

موقعیت مرکزی نزدیک به موزه ها، آرام در شب و مناسب برای خانواده ها.

51.51750, -0.13065

موقعیت مرکزی نزدیک به بارها و رستوران ها. صدای بلند و شلوغ در شب، برای گروه ها خوب است.

51.45712, 0.01146

موقعیت مسکونی دور از مرکز شهر.

51.51271, -0.09933

موقعیت مرکزی نزدیک به رودخانه. شب آرام و مناسب برای خانواده ها.

51.58502, -0.06445

موقعیت مسکونی دور از مرکز شهر.

این توضیحات کیفی همراه با هر گونه اطلاعات کاربر یا ترجیحات را می توان در درخواست شما به 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 ارائه دهد، باید در مورد ساختار خروجی دقیق تر صحبت کنیم، بنابراین می دانیم وقتی آن را با کد پرس و جو می کنیم چه انتظاری داشته باشیم. برای این کار، می‌توانیم با استفاده از فیلد answerSchema در 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 را امتحان کنید تا امتیازهای مکان روشنگری را ایجاد کنید تا به مشتریانتان کمک کنید تا تصمیمات مبتنی بر موقعیت مکانی آگاهانه بگیرند!

مشارکت کنندگان

Henrik Valve | مهندس DevX