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

هذا المستند هو تحديث لمقالة أقدم استخدمت إصدارات سابقة من واجهات برمجة تطبيقات GMP. تم تعديل هذا المحتوى ليتضمّن الإصدار الجديد من 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 Maps Platform المفعّلة في Google Cloud Console. للحصول على شرح أكثر تفصيلاً، يُرجى الاطّلاع على مستندات البدء في استخدام Google Maps Platform.

تتوفّر طلبات 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).

صور "التجوّل الافتراضي" للمبنى رقم 5

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

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

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

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

الخاتمة

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

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

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

بدء استخدام "منصة خرائط 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"