نکاتی برای ایجاد بهترین تجربه کاربری هنگام پیمایش به مکان‌ها با ماشین

این سند به‌روزرسانی مقاله‌ای قدیمی‌تر است که از نسخه‌های قبلی APIهای GMP استفاده می‌کرد. این محتوا با نسخه جدید Places API که در سال‌های 2023-24 و Routes API که در سال 2023 راه‌اندازی شده‌اند، به‌روزرسانی شده است.

معمولاً وقتی کاربر به سمت یک نقطه مورد علاقه (POI) رانندگی می‌کند، در واقع به ناوبری به مکانی نزدیک مانند پارکینگ یا نقطه دسترسی نیاز دارد. راننده‌ای را تصور کنید که باید به فرودگاه یا مرکز خرید برود. راننده هنگام رفتن به فرودگاه سعی می‌کند به جای مرکز محوطه فرودگاه، به یک ترمینال یا محل پیاده شدن برسد. به همین ترتیب، یک پارکینگ در کنار مرکز خرید می‌تواند گزینه بسیار بهتری برای کاربری باشد که ماشین دارد. در این حالت، هنگام توسعه یک برنامه یا سرویس برای راهنمایی راننده، ابتدا مکانی را که قرار است به آن برود پیدا کنید و سپس مقاصد اختیاری نزدیک به آن مکان را به راننده پیشنهاد دهید. این رویکرد به شما امکان می‌دهد با یک تلاش توسعه‌ای کوچک اما هوشمندانه که از داده‌های مکانی ارائه شده توسط پلتفرم نقشه‌های گوگل بهره می‌برد، خدمات بهتری به مشتریان خود ارائه دهید و نشان دهید که برای وقت آنها ارزش قائل هستید.

ما نشان خواهیم داد که چگونه می‌توانید از API جدید Places و API Routes به ترتیب یا ترکیبی برای شناسایی مکان مناسب برای پارک در کنار مقصد خود استفاده کنید. هدف این راه حل، حذف عدم قطعیت و تعاملات چندگانه برای یافتن جای پارک هنگام رانندگی و نزدیک شدن به مقصد نهایی است. به دو مثال از چگونگی پیاده‌سازی دقیق این موارد نگاهی بیندازید.

مثال ۱ - یک جاذبه گردشگری بدون پارکینگ

مکانی را انتخاب کنید که مستقیماً به کنار جاده متصل نباشد تا مسیر جداگانه‌ای برای آن انتخاب شود، مقصد نوتردام در پاریس است و به عنوان نقطه شروع از ایستگاه راه‌آهن Gare de l'Est (48.87697775149635، 2.3592247806755564) استفاده خواهیم کرد.

راننده ایستگاه را حدود ۱۶ دقیقه در شمال نوتردام ترک می‌کند. نوتردام یک جاذبه گردشگری معروف در جزیره‌ای با دسترسی از طریق پل، برخی خیابان‌های یک طرفه و عدم وجود پارکینگ بزرگ در نزدیکی آن است، بنابراین این باید یک چالش جالب باشد.

۱. درخواست API را قرار می‌دهد

این مثال از درخواست API مکان‌ها، از جستجوی متنی برای یافتن نوتردام استفاده می‌کند. برای جزئیات بیشتر به مستندات توسعه‌دهنده مراجعه کنید. "$APIKEY" در این مثال‌ها، کلید API شما برای APIهای مکان‌ها و مسیرهای پلتفرم نقشه‌های گوگل است که در کنسول ابری گوگل فعال شده‌اند. برای توضیحات بیشتر، به مستندات شروع به کار با پلتفرم نقشه‌های گوگل مراجعه کنید.

درخواست‌های جدید 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"
      }
    }
  ]
}

همانطور که می‌بینید، مختصات واقعاً نوتردام را نشان می‌دهند.

به عنوان یک توسعه‌دهنده یا ارائه‌دهنده خدمات، ایده خوبی است که به طور خودکار از راننده بپرسید "به دنبال پارکینگ در نزدیکی نوتردام هستید؟" یا اگر راننده وسیله نقلیه الکتریکی دارد، ممکن است بخواهید یک ایستگاه شارژ را جستجو کنید. تجربه کاربری بسته به دستگاه و صفحه نمایش متفاوت خواهد بود، اما یک متن محاوره‌ای ظریف که پس از مدت کوتاهی ناپدید می‌شود، می‌تواند در این مورد ارزش بررسی داشته باشد. برای یافتن پارکینگ در نزدیکی نوتردام، یک جستجوی API Places در نزدیکی با انواع "parking" و "electric_vehicle_charging_station" با شعاع ۵۰۰ متر انجام دهید. مثال زیر نتایج را به سمت مناطق پارکینگ در فاصله ۵۰۰ متری نوتردام متمایل می‌کند.

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

اولین نتیجه یک ایستگاه شارژ در آدرس‌های ۴۸.۸۵۴۹۸۱ و ۲.۳۵۰۶۲۹ است، هرچند تا زمانی که این مثال را اجرا کنید، نتایج شما ممکن است متفاوت باشد. از این مکان در بخش بعدی که درخواست Routes API را انجام می‌دهیم، استفاده کنید.

۲. درخواست API مسیرها

برای پیدا کردن مسیر از ایستگاه به یک ایستگاه شارژ نزدیک به نوتردام، باید یک درخواست از 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'

پاسخ API مسیرها معمولاً شامل چندین پیشنهاد مسیر است. برای گنجاندن داده‌های مسیر در پاسخ، "routes.legs" را در fieldmask تعریف کنید. هر مسیر از چندین "leg" تشکیل شده است و آنها شامل چندین "step" هستند که مسافت سفر و مختصات را نشان می‌دهند. برای یافتن مختصات نهایی قابل دسترسی با ماشین، از فیلد "endLocation" آخرین مرحله از آخرین مرحله در مسیری که انتخاب کرده‌اید استفاده کنید. "latitude": 48.854937299999996, "longitude": 2.3505841999999997

این مکان ممکن است اولین انتخاب به نظر نرسد، اما وقتی به نقشه یا نمای خیابان گوگل نگاه می‌کنید، متوجه خواهید شد که این مکان در فاصله بسیار کوتاهی از کلیسای نوتردام، حدود ۶-۷ دقیقه پیاده‌روی، قرار دارد.

مسیر پیاده‌روی از محل پارکینگ ایستگاه شارژ تا نوتردام

خلاصه برای مثال ۱

همانطور که می‌بینید، پیدا کردن جای پارک برای یک ماشین تنها به چند فراخوانی API و نمایش پیشنهاد به راننده نیاز دارد. این باعث صرفه‌جویی در زمان کاربران شما می‌شود زیرا آنها در خیابان‌های یک‌طرفه رانندگی نمی‌کنند یا سعی نمی‌کنند در یک جاذبه توریستی شلوغ جایی برای پارک کردن ماشین پیدا کنند. به طور خلاصه، ما درخواست‌های API زیر را انجام دادیم:

• درخواست جستجوی متن API مکان‌ها برای یافتن مختصات نوتردام
• جستجوی API مکان‌ها در نزدیکی برای یافتن محل پارکینگ با ایستگاه شارژ ماشین الکتریکی در فاصله ۵۰۰ متری از آن مختصات
• درخواست API مسیرها برای یافتن مسیری به ایستگاه شارژ

مثال ۲ - راهنمایی به سمت ترمینال در یک فرودگاه بزرگ

مثال دیگری را در نظر بگیرید که راننده سعی دارد به منطقه‌ی بزرگی برسد که چندین مکان، نقطه‌ی مورد علاقه یا نقاط بالقوه‌ی پیاده شدن دارد. راننده از ورزشگاه ومبلی، انگلستان (51.557263604707224، -0.2794575145680608) حرکت می‌کند و سعی دارد به ترمینال ۵ فرودگاه هیترو لندن برسد.

نکته‌ی جالب در مورد تکمیل خودکار جدید Places API، قابلیت تعریف انواع اصلی به عنوان معیارهای جستجو در ترکیب با پیش‌بینی 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

عبارت بالا فهرستی از ترمینال‌ها و نقاط تحویل مسافران در هر ترمینال را به ما می‌دهد. از فهرست نتایج می‌توانیم «ترمینال ۵ فرودگاه هیترو لندن» و شناسه مکان آن را پیدا کنیم:

"place_id" : "ChIJo21hnPxxdkgRksRL0KQRWII",

با استفاده از پارامتر "placeId" می‌توانیم به 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.4896789000000003) را پیدا خواهید کرد.

خلاصه برای مثال ۲

مانند مثال قبلی، تلاش توسعه برای ارائه راهنمایی بهتر به راننده بسیار کم است و مزایای صرفه‌جویی در زمان برای راننده قابل اندازه‌گیری است. ما درخواست‌های زیر را انجام دادیم:

• درخواست تکمیل خودکار Places API (جدید) برای یافتن ترمینال ۵ فرودگاه هیترو
• درخواست API مسیرها برای دریافت مسیری از ومبلی به ترمینال ۵

این مثال فقط بخش کوچکی از ویژگی‌های جدید Places API را نشان می‌دهد. نگاهی به برخی از انواع مکان‌های جدید مانند باند فرودگاه و فرودگاه بین‌المللی بیندازید.

نتیجه‌گیری

همانطور که می‌بینید، تلاش توسعه‌ای مورد نیاز برای ارائه خدمات ممتاز به مشتریانی که با ماشین سفر می‌کنند، نسبتاً کم است و می‌توانید نشان دهید که چگونه به نیازهای مشتریان خود فکر می‌کنید.

برای اهداف توسعه، می‌توانید از بسیاری از کتابخانه‌ها و ابزارهای موجود برای کمک به ساخت خدمات برای مشتریان خود استفاده کنید. نگاهی به مخزن گیت‌هاب ما که در دسترس عموم است برای پلتفرم نقشه‌های گوگل بیندازید.

اقدامات بعدی

شروع کار با GMP: https://developers.google.com/maps/get-started

مطالعه بیشتر پیشنهادی

مستندات تکمیل خودکار API مکان‌ها (جدید): https://developers.google.com/maps/documentation/places/web-service/place-autocomplete

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

مشارکت‌کنندگان

نویسنده اصلی: Mikko Toivanen | مهندس راه حل های پلتفرم نقشه های گوگل