نصائح لإنشاء أفضل تجربة للمستخدم عند الانتقال إلى المواقع الجغرافية باستخدام سيارة

هذا المستند هو تحديث لمقالة أقدم استخدمت إصدارات سابقة من واجهات برمجة التطبيقات في "منصة Google للتسويق". تم تعديل هذا المحتوى ليتضمّن الإصدار الجديد من Places API الذي تم إطلاقه في الفترة 2023-2024 وRoutes API الذي تم إطلاقه في 2023.

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

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

المثال 1 - معلم سياحي لا يتضمّن موقفًا للسيارات

اختَر موقعًا جغرافيًا غير متصل مباشرةً بجانب الطريق، وذلك لكي يتم استرداد مسار بشكل منفصل، ويكون الوجهة هي كاتدرائية نوتردام في باريس، ونقطة البداية هي محطة قطار غار دو ليست (48.87697775149635, 2.3592247806755564).

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

1. طلب البيانات من Places API

يستخدم طلب بيانات من واجهة برمجة التطبيقات Places API هذا البحث النصي للعثور على نوتردام. لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات المطوّرين. إنّ "$APIKEY" في هذه الأمثلة هو مفتاح واجهة برمجة التطبيقات الذي تستخدمه في واجهات برمجة التطبيقات Places وRoutes من منصة خرائط Google المفعّلة في Google Cloud Console. للحصول على شرح أكثر تفصيلاً، يُرجى الاطّلاع على مستندات البدء في استخدام منصة خرائط Google.

تتضمّن طلبات Places API الجديدة تنسيقًا جديدًا. لم تعُد حقول الاستجابة ثابتة، وعليك كمطوّر تحديد fieldmask في العنوان. يتم تحديد استخدام fieldmask في المستندات.

curl -X POST --data @notre_dame.json \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress,places.location' \
'https://places.googleapis.com/v1/places:searchText'

مع محتوى "notre_date.json" لمَعلمات البحث:

{
   "textQuery": "Notre Dame, Paris",
   "languageCode": "en"
}

يقدّم الردّ على الطلب أعلاه إحداثيات خطوط الطول والعرض التالية:

{
  "places": [
    {
      "id": "ChIJATr1n-Fx5kcRjQb6q6cdQDY",
      "formattedAddress": "6 Parvis Notre-Dame - Pl. Jean-Paul II, 75004 Paris, France",
      "location": {
        "latitude": 48.852968200000007,
        "longitude": 2.3499021
      },
      "displayName": {
        "text": "Cathédrale Notre-Dame de Paris",
        "languageCode": "en"
      }
    }
  ]
}

كما ترى، تشير الإحداثيات بالفعل إلى "كاتدرائية نوتردام".

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

curl -X POST -d '{
  "includedTypes": ["parking", "electric_vehicle_charging_station"],
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 48.852968200000007,
        "longitude": 2.3499021},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H "X-Goog-FieldMask: places.displayName,places.location" \
https://places.googleapis.com/v1/places:searchNearby

النتيجة الأولى هي محطة شحن تقع عند الإحداثيات 48.854981 و2.350629، ولكن قد تختلف النتائج عند تنفيذ هذا المثال. استخدِم هذا الموقع الجغرافي في الجزء التالي حيث نرسل طلب بيانات من واجهة برمجة التطبيقات إلى Routes API.

2. طلب Routes API

للعثور على المسار من المحطة إلى محطة شحن قريبة من كاتدرائية نوتردام، عليك إرسال طلب بيانات من واجهة برمجة التطبيقات إلى Routes API. ما عليك سوى ضبط مَعلمتَي نقطة الانطلاق والوجهة. يمكنك الاطّلاع على مستندات المطوّرين لمعرفة المزيد من الخيارات.

curl -X POST -d '{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 48.87697775149635,
        "longitude": 2.3592247806755564
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
       "latitude": 48.854981,
        "longitude": 2.350629
      }
    }
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "departureTime": "2024-05-16T15:01:23.045123456Z",
  "computeAlternativeRoutes": false,
  "routeModifiers": {
    "avoidTolls": false,
    "avoidHighways": false,
    "avoidFerries": false
  },
  "languageCode": "en-US",
  "units": "METRIC"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.legs,routes.polyline.encodedPolyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

عادةً ما يحتوي الردّ من Routes API على اقتراحات متعددة للطرق. لتضمين بيانات المسار في الرد، حدِّد "routes.legs" في fieldmask. يتألف كل مسار من عدة "مقاطع"، ويتضمّن كل مقطع عدة "خطوات" تعرض مسافة التنقّل والإحداثيات. للعثور على الإحداثيات النهائية التي يمكن الوصول إليها بالسيارة، استخدِم حقل "endLocation" (الموقع الجغرافي النهائي) في الخطوة الأخيرة من آخر جزء من المسار الذي اخترته. "latitude": 48.854937299999996, "longitude": 2.3505841999999997

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

مسار المشي من موقف سيارات محطة الشحن إلى كاتدرائية نوتردام

ملخّص المثال 1

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

• طلب بحث نصي في Places API للعثور على إحداثيات كاتدرائية نوتردام
• طلب بحث عن أماكن قريبة باستخدام Places API للعثور على موقف سيارات مزوّد بمحطة شحن للسيارات الكهربائية على بُعد 500 متر من الإحداثيات المحدّدة
• طلب بيانات من واجهة برمجة التطبيقات Routes API للعثور على مسار إلى محطة الشحن

المثال 2: توجيه المستخدم إلى صالة في مطار كبير

لنفترض مثالاً آخر يحاول فيه السائق الوصول إلى منطقة كبيرة تتضمّن مواقع جغرافية أو نقاط اهتمام أو نقاط تسليم محتملة متعددة. يغادر السائق من ملعب ويمبلي في المملكة المتحدة (51.557263604707224، -0.2794575145680608) ويحاول الوصول إلى مبنى الركاب 5 في مطار لندن هيثرو.

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

curl -X POST -d '{
  "input": "Heathrow",
  "includedPrimaryTypes": ["airport", "parking"]
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
https://places.googleapis.com/v1/places:autocomplete

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

"place_id" : "ChIJo21hnPxxdkgRksRL0KQRWII",

باستخدام المَعلمة "placeId"، يمكننا إخبار واجهة Routes API بأنّنا نحاول الوصول إلى مكان معيّن بدلاً من إحداثيات عشوائية.

curl -X POST -d '{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 51.557263604707224,
        "longitude": -0.2794575145680608
      }
    }
  },
  "destination":{
    "placeId": "ChIJo21hnPxxdkgRksRL0KQRWII"
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "departureTime": "2024-05-16T15:01:23.045123456Z",
  "computeAlternativeRoutes": false,
  "languageCode": "en-US",
  "units": "METRIC"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: $APIKEY" \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.legs,routes.polyline.encodedPolyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

مرة أخرى، كما هو الحال في المثال السابق، من خلال قراءة جميع الخطوات في رد JSON، ستجد الجزء الأخير من الرحلة وإحداثيات خطوط الطول والعرض الخاصة بالمواقع الجغرافية النهائية (51.4714348، "خط الطول": -0.48967890000000003).

ملخّص المثال 2

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

• طلب إكمال تلقائي (جديد) من Places API للعثور على مبنى الركاب 5 في مطار هيثرو
• طلب بيانات من واجهة برمجة التطبيقات موجَّه إلى Routes API للحصول على مسار من ويمبلي إلى المحطة 5

هذا المثال يقدّم لمحة بسيطة عن ميزات Places API الجديدة. اطّلِع على بعض أنواع الأماكن الجديدة، مثل مهبط الطائرات والمطار الدولي.

الخاتمة

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

لأغراض التطوير، يمكنك استخدام العديد من المكتبات والأدوات المتاحة لمساعدتك في إنشاء الخدمات لعملائك. يمكنك الاطّلاع على مستودع GitHub المتاح للجميع لمنصة خرائط Google.

الإجراءات التالية

بدء استخدام "منصة خرائط Google": https://developers.google.com/maps/get-started

محتوى إضافي مقترَح للقراءة

مستندات ميزة "الإكمال التلقائي" في Places API (الجديدة): https://developers.google.com/maps/documentation/places/web-service/place-autocomplete

مستندات Routes API: https://developers.google.com/maps/documentation/routes

المساهمون

المؤلف الرئيسي: ميكو تويفانن | مهندس حلول في "منصة خرائط Google"