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

هذا المستند هو تحديث لمقالة أقدم استخدمت إصدارات سابقة من واجهات برمجة تطبيقات 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).

ملخّص المثال 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"