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

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

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

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

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

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

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

1. طلب Places API

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

تتضمّن طلبات Places API الجديدة تنسيقًا جديدًا. لم تعُد حقول الاستجابة ثابتة، ويجب عليك كأحد المطوّرين تحديد قناع حقل في العنوان. يتم تحديد استخدام 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"
      }
    }
  ]
}

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

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

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.

1. **طلب Routes API **

للعثور على المسار من المحطة إلى محطة شحن قريبة من Notre Dame، عليك إرسال طلب إلى 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 عادةً على اقتراحات متعددة للمسارات. لتضمين data مسار في الاستجابة، حدِّد "routes.legs" في قناع الحقول. يتألّف كل مسار من عدّة "مراحل" تحتوي على عدّة "خطوات" تعرض المسافة التي يتم قطعها والإحداثيات. للعثور على الإحداثيات النهائية التي يمكن الوصول إليها بسيارة، استخدِم الحقل "endLocation" للخطوة الأخيرة من القسم الأخير في المسار الذي اخترته. "latitude": 48.854937299999996, "longitude": 2.3505841999999997

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

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

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

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

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

المثال 2: توجيه إلى مبنى في مطار كبير

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

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

curl -X POST -d '{
  "input": "Heathrow",
  "includedPrimaryTypes": ["airport"]
}' \
-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، "longitude": -0.48967890000000003).

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

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

• طلب إكمال تلقائي (جديد) من Places API للعثور على مبنى الركاب 5 في مطار هيثرو
• طلب Routes API للحصول على مسار من Wembley إلى المحطة 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"