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

الهدف

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

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

يمكنك طلب 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