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

الهدف

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

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

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

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

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

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

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

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

عرض توضيحي

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

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

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

• مطعم
• متنزه
• clothing_store
• متحف
• coffee_shop

بعد ذلك، يمكنك منح وزن لكل نوع من أنواع الأماكن هذه، ما يعكس أهميته النسبية في النتيجة النهائية. يجب تحديد الأوزان استنادًا إلى العوامل الأكثر أهمية لحالة الاستخدام وإعدادات المستخدم المفضّلة. في هذا المثال، سيكون مقياس الترجيح بين 0 و1 على النحو التالي:

Call Places Aggregate API

بعد أن أصبحت لديك قائمة بأنواع الأماكن التي تهمّك، الخطوة التالية هي طلب بيانات من واجهة برمجة التطبيقات Places Aggregate API.

تتطلّب واجهة برمجة التطبيقات Places Aggregate API فلتر موقع جغرافي. في هذا المثال، استخدِم circle، مع تحديد latLng كمركز موقع الفندق وradius بقيمة 500 متر. يمكنك أيضًا ضبط ratingFilter لعرض الأماكن التي حصلت على تقييم يتراوح بين 3.8 و 5، مع استبعاد الأماكن التي حصلت على تقييم أقل من هذه الأرقام.

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

اطّلِع على قسم FILTER BY LOCATION في مستندات واجهة برمجة التطبيقات 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
        }
    }
}'

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

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

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

الخيار 2: استخدام Gemini Developer API

كبديل لاستخدام خوارزمية محلية، تقدّم واجهة برمجة التطبيقات Developer API في Gemini طريقة فعّالة للقيام بحساب نتيجة الموقع الجغرافي المخصّصة لجميع المواقع الجغرافية. ما عليك سوى تقديم بيانات العدد والترجيح مع تعليمات النظام لجميع مواقع الفنادق.

تكون هذه الطريقة مفيدة بشكل خاص إذا كانت لديك معلومات دقيقة تريد تضمينها في العملية الحسابية، مثل:

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

يمكن لواجهة برمجة التطبيقات 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 اليوم لتحديد تقييمات مواقع جغرافية مفيدة لمساعدة عملائك في اتّخاذ قرارات مدروسة تستند إلى الموقع الجغرافي.

المساهمون

Henrik Valve | مهندس DevX