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

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

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

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

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

يعد هذا المثال مجرد بداية لميزات واجهة برمجة التطبيقات الجديدة الخاصة بالأماكن. ألق نظرة على بعض أنواع الأماكن الجديدة مثل مهبط الطائرات والمطار الدولي.

الخاتمة

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

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

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

البدء باستخدام GMP : 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"