استخدام واجهة برمجة التطبيقات Places Aggregate API لإنشاء نتيجة مخصّصة للموقع الجغرافي

الهدف

عند البحث عن مكان مثالي للإقامة، سواء كان فندقًا لقضاء عطلتك القادمة أو شقة مناسبة للعائلات، غالبًا ما تكون عملية مقارنة الخيارات المتعددة محبطة وتستغرق وقتًا طويلاً. ماذا لو كان بإمكانك تسهيل هذه العملية على المستخدمين من خلال تقديم مقياس مخصّص يكشف مدى ملاءمة فندق معيّن للسياح أو ترتيب عروض الشقق استنادًا إلى مدى ملاءمتها للعائلات، ما يحوّل مهمة شاقة إلى قرار سهل؟

يوضّح هذا المستند كيفية استخدام Places Aggregate API لإنشاء نتائج مخصّصة وديناميكية للمواقع الجغرافية استنادًا إلى كثافة الأماكن ضمن منطقة جغرافية محدّدة. ستوضّح النتيجة، وهي ترتيب رقمي مقارنةً بالمعايير المحدّدة، مدى ملاءمة الموقع الجغرافي لاحتياجات المستخدمين على الفور.

لنفترض أنّك تروّج لفنادق في مدينة معيّنة وتريد إبراز الفنادق الواقعة في المناطق السياحية الأكثر جاذبية من خلال إنشاء تقييم "مناسب للسياح". استخدِم Places Aggregate API لاحتساب عدد أنواع الأماكن ذات الصلة بالقرب من كل فندق. على سبيل المثال، أنت تعلم أنّ عملاءك يفضّلون الفنادق التي تقع بالقرب من عدد من الأماكن التالية:

• المطاعم والمقاهي
• المتنزهات والمتاحف
• متاجر ملابس

من خلال تطبيق أوزان الأهمية على أعداد أنواع الأماكن المحدّدة هذه، يمكنك احتساب درجة إجمالية لكل موقع جغرافي للفندق. تعكس النتيجة مدى ملاءمة الموقع الجغرافي بشكل عام، استنادًا إلى الأماكن القريبة. يجب أن تتوافق الأوزان المحدّدة لكل نوع مكان مع حالة الاستخدام المحدّدة والأهمية التي يوليها الجمهور المستهدَف. سيستخدم هذا المستند النتيجة مناسب للسياح كمثال رئيسي، ولكن يمكن إنشاء النتيجة الخاصة بك لتعكس الخصائص الديمغرافية واحتياجات المستخدمين.

المتطلبات الأساسية

قبل قراءة هذا المستند، ننصحك بالاطّلاع على المستندات التالية:

• مستندات مطوّري Places Aggregate API للتعرّف على التفاصيل الفنية والمَعلمات المتاحة
• [اختياري] مستندات المطوّرين لواجهة Gemini Developer API لفهم كيفية طلب Gemini باستخدام واجهة برمجة تطبيقات، ويتم استخدامها في هذا المستند كخيار لإنشاء نتيجة الموقع الجغرافي المخصّصة.

عرض توضيحي

يعرض هذا العرض التوضيحي مثالاً على كيفية عمل نتيجة الموقع الجغرافي المخصّصة. اختَر مدينة من القائمة المنسدلة، ثم انقر على الزر احتساب النتيجة المخصّصة لعرض نتيجة الموقع الجغرافي المخصّصة لخمسة مواقع جغرافية تمّت تعبئتها مسبقًا.

اختيار أنواع الأماكن ذات الصلة

تتمثّل الخطوة الأولى لإنشاء نتيجة الموقع الجغرافي المخصّصة في تحديد أنواع الأماكن ذات الصلة بعملائك من الجدول (أ). أثناء إنشاء تقييم مناسب للسياح، اخترنا أنواع الأماكن التالية التي يريد السياح الإقامة بالقرب منها:

• مطعم
• متنزه
• 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 للتعرّف على الخيارات المتاحة لك.

استدعِ واجهة برمجة التطبيقات Call 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
        }
    }
}'

بعد إكمال جميع الطلبات إلى واجهة برمجة التطبيقات، ستتوفّر لديك بيانات مشابهة لما يلي لكل موقع جغرافي:

إنشاء نتيجة الموقع الجغرافي المخصّص

بعد أن أصبح لديك عدد الأماكن ووزن كل نوع من أنواع الأماكن لكل موقع جغرافي، يمكنك الآن إنشاء نتيجة الموقع الجغرافي المخصّصة. سنناقش خيارَين في هذا القسم، وهما استخدام خوارزمية محلية أو استخدام 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 اليوم لإنشاء نتائج مواقع جغرافية مفيدة تساعد عملاءك في اتخاذ قرارات مدروسة تستند إلى الموقع الجغرافي.

المساهمون

هنريك فالف | مهندس DevX