خدمات مسیرها

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)
نکته: کتابخانه‌های سمت سرور

نمای کلی

شما می‌توانید با استفاده از شیء DirectionsService مسیرها را (با استفاده از روش‌های مختلف حمل و نقل) محاسبه کنید. این شیء با سرویس مسیریابی API نقشه‌های گوگل ارتباط برقرار می‌کند که درخواست‌های مسیر را دریافت کرده و یک مسیر کارآمد را برمی‌گرداند. زمان سفر عامل اصلی بهینه‌سازی است، اما عوامل دیگری مانند مسافت، تعداد چرخش‌ها و بسیاری موارد دیگر نیز ممکن است در نظر گرفته شوند. شما می‌توانید خودتان این نتایج مسیرها را مدیریت کنید یا از شیء DirectionsRenderer برای رندر این نتایج استفاده کنید.

هنگام مشخص کردن مبدا یا مقصد در یک درخواست جهت‌یابی، می‌توانید یک رشته پرس‌وجو (مثلاً "شیکاگو، ایلینوی" یا "داروین، نیوساوت ولز، استرالیا")، یک مقدار LatLng یا یک شیء Place را مشخص کنید.

سرویس Directions می‌تواند با استفاده از مجموعه‌ای از نقاط مسیر، مسیرهای چند قسمتی را برگرداند. مسیرها به صورت یک چندخطی که مسیر را روی نقشه ترسیم می‌کند، یا علاوه بر آن به صورت مجموعه‌ای از توضیحات متنی در یک عنصر <div> نمایش داده می‌شوند (برای مثال، "به سمت راست به رمپ پل ویلیامزبورگ بپیچید").

شروع به کار

قبل از استفاده از سرویس Directions در Maps JavaScript API، ابتدا مطمئن شوید که Directions API (Legacy) در کنسول Google Cloud، در همان پروژه‌ای که برای Maps JavaScript API تنظیم کرده‌اید، فعال شده است.

برای مشاهده لیست API های فعال خود:

  1. به کنسول گوگل کلود بروید.
  2. روی دکمه‌ی «انتخاب پروژه» کلیک کنید، سپس همان پروژه‌ای را که برای Maps JavaScript API تنظیم کرده‌اید، انتخاب کنید و روی «باز کردن» کلیک کنید.
  3. از لیست APIهای موجود در داشبورد ، به دنبال Directions API (Legacy) بگردید.
  4. اگر API را در لیست مشاهده کردید، همه چیز آماده است. اگر API در لیست نیست، آن را در https://console.cloud.google.com/apis/library/directions-backend.googleapis.com فعال کنید.

قیمت‌گذاری و سیاست‌ها

قیمت‌گذاری

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

سیاست‌ها

استفاده از سرویس Directions باید مطابق با سیاست‌های شرح داده شده برای Directions API (Legacy) باشد.

درخواست‌های مسیر

دسترسی به سرویس Directions به صورت غیرهمزمان است، زیرا API نقشه‌های گوگل نیاز به برقراری ارتباط با یک سرور خارجی دارد. به همین دلیل، شما باید یک متد callback برای اجرا پس از تکمیل درخواست ارسال کنید. این متد callback باید نتیجه(ها) را پردازش کند. توجه داشته باشید که سرویس Directions ممکن است بیش از یک مسیر سفر ممکن را به صورت آرایه‌ای از routes[] برگرداند.

برای استفاده از جهت‌ها در API جاوا اسکریپت Maps، یک شیء از نوع DirectionsService ایجاد کنید و DirectionsService.route() را برای شروع یک درخواست به سرویس Directions فراخوانی کنید و یک شیء DirectionsRequest را به صورت تحت‌اللفظی حاوی عبارات ورودی و یک متد callback برای اجرا پس از دریافت پاسخ به آن ارسال کنید.

شیء DirectionsRequest به صورت تحت‌اللفظی شامل فیلدهای زیر است:

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidFerries: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

این فیلدها در زیر توضیح داده شده‌اند:

  • origin ( الزامی ) مکان شروع محاسبه جهت‌ها را مشخص می‌کند. این مقدار می‌تواند به صورت یک String (مثلاً "شیکاگو، ایلینوی")، یک مقدار LatLng یا یک شیء Place مشخص شود. اگر از یک شیء Place استفاده می‌کنید، می‌توانید یک شناسه مکان ، یک رشته پرس‌وجو یا یک مکان LatLng مشخص کنید. می‌توانید شناسه‌های مکان را از سرویس‌های Geocoding، Place Search و Place Autocomplete در Maps JavaScript API بازیابی کنید. برای مثالی از استفاده از شناسه‌های مکان از Place Autocomplete، به Place Autocomplete و Directions مراجعه کنید.
  • destination ( الزامی ) نقطه پایانی برای محاسبه جهت‌ها را مشخص می‌کند. گزینه‌ها مشابه فیلد origin هستند که در بالا توضیح داده شد.
  • travelMode ( الزامی ) مشخص می‌کند که هنگام محاسبه مسیرها از چه نوع وسیله حمل و نقلی استفاده شود. مقادیر معتبر در حالت‌های سفر زیر مشخص شده‌اند.
  • transitOptions ( اختیاری ) مقادیری را مشخص می‌کند که فقط برای درخواست‌هایی اعمال می‌شوند که travelMode آنها TRANSIT است. مقادیر معتبر در Transit Options در زیر توضیح داده شده‌اند.
  • drivingOptions ( اختیاری ) مقادیری را مشخص می‌کند که فقط برای درخواست‌هایی اعمال می‌شوند که travelMode در آنها DRIVING است. مقادیر معتبر در Driving Options در زیر توضیح داده شده‌اند.

  • unitSystem ( اختیاری ) مشخص می‌کند که هنگام نمایش نتایج از چه سیستم واحدی استفاده شود. مقادیر معتبر در Unit Systems زیر مشخص شده‌اند.

  • waypoints[] ( اختیاری ) آرایه‌ای از DirectionsWaypoint ها را مشخص می‌کند. Waypointها با مسیریابی مسیر از طریق مکان(های) مشخص شده، آن را تغییر می‌دهند. یک Waypoint به صورت یک شیء تحت‌اللفظی با فیلدهای نشان داده شده در زیر مشخص می‌شود:

    • location موقعیت مکانی نقطه‌ی مسیر را به صورت یک LatLng ، یک شیء Place یا یک String که به صورت جغرافیایی کدگذاری می‌شود، مشخص می‌کند.
    • stopover یک مقدار بولی است که نشان می‌دهد نقطه‌ی بین‌راهی، یک ایستگاه در مسیر است که باعث تقسیم مسیر به دو مسیر می‌شود.

    (برای اطلاعات بیشتر در مورد نقاط مسیر، به بخش «استفاده از نقاط مسیر در مسیرها» در زیر مراجعه کنید.)

  • optimizeWaypoints ( اختیاری ) مشخص می‌کند که مسیر با استفاده از waypoints ارائه شده می‌تواند با مرتب‌سازی مجدد نقاط مسیر به ترتیب کارآمدتر، بهینه شود. اگر true ، سرویس Directions، waypoints مرتب‌شده را در فیلد waypoint_order برمی‌گرداند. (برای اطلاعات بیشتر، به بخش «استفاده از نقاط مسیر در مسیرها» در زیر مراجعه کنید.)
  • provideRouteAlternatives ( اختیاری ) وقتی روی true تنظیم شود، مشخص می‌کند که سرویس Directions ممکن است بیش از یک مسیر جایگزین در پاسخ ارائه دهد. توجه داشته باشید که ارائه مسیرهای جایگزین ممکن است زمان پاسخ از سرور را افزایش دهد. این فقط برای درخواست‌هایی بدون نقاط مسیر میانی در دسترس است.
  • avoidFerries ( اختیاری ) وقتی روی true تنظیم شده باشد، نشان می‌دهد که مسیر(های) محاسبه‌شده باید در صورت امکان از کشتی‌ها اجتناب کنند.
  • avoidHighways ( اختیاری ) وقتی روی true تنظیم شود، نشان می‌دهد که مسیر(های) محاسبه‌شده باید در صورت امکان از بزرگراه‌های اصلی اجتناب کنند.
  • avoidTolls ( اختیاری ) وقتی روی true تنظیم شده باشد، نشان می‌دهد که مسیر(های) محاسبه‌شده باید در صورت امکان از جاده‌های عوارض‌دار اجتناب کنند.
  • region ( اختیاری ) کد منطقه را مشخص می‌کند که به عنوان یک مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده است. (برای اطلاعات بیشتر به Region Biasing در زیر مراجعه کنید.)

در زیر یک نمونه از DirectionsRequest آمده است:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

حالت‌های سفر

هنگام محاسبه مسیر، باید مشخص کنید که از کدام روش حمل و نقل استفاده خواهید کرد. در حال حاضر روش‌های سفر زیر پشتیبانی می‌شوند:

  • DRIVING ( پیش‌فرض ) مسیرهای رانندگی استاندارد را با استفاده از شبکه جاده‌ای نشان می‌دهد.
  • BICYCLING مسیرهای دوچرخه‌سواری را از طریق مسیرهای دوچرخه‌سواری و خیابان‌های مورد نظر درخواست می‌کند.
  • TRANSIT درخواست مسیر از طریق مسیرهای حمل و نقل عمومی را می‌دهد.
  • WALKING درخواست مسیر پیاده‌روی از طریق مسیرهای عابر پیاده و پیاده‌روها را می‌دهد.

برای تعیین میزان پشتیبانی یک کشور از مسیرها ، به جزئیات پوشش پلتفرم نقشه‌های گوگل مراجعه کنید. اگر برای منطقه‌ای درخواست مسیر کنید که آن نوع مسیر در آن موجود نیست، پاسخ، DirectionsStatus = " ZERO_RESULTS " را برمی‌گرداند.

نکته : مسیرهای پیاده‌روی ممکن است شامل مسیرهای عابر پیاده‌ی مشخص نباشند، بنابراین مسیرهای پیاده‌روی در DirectionsResult هشدارهایی را برمی‌گردانند. این هشدارها باید همیشه به کاربر نمایش داده شوند. اگر از DirectionsRenderer پیش‌فرض استفاده نمی‌کنید، مسئولیت نمایش هشدارها بر عهده‌ی خودتان است.

گزینه‌های حمل و نقل عمومی

گزینه‌های موجود برای درخواست مسیر، بسته به حالت سفر، متفاوت است. هنگام درخواست مسیر حمل و نقل عمومی، گزینه‌های avoidHighways ، avoidTolls ، waypoints[] و optimizeWaypoints نادیده گرفته می‌شوند. می‌توانید گزینه‌های مسیریابی مخصوص حمل و نقل عمومی را از طریق شیء TransitOptions به صورت تحت‌اللفظی مشخص کنید.

مسیرهای حمل و نقل عمومی به زمان حساس هستند. مسیرها فقط برای زمان‌های آینده برگردانده می‌شوند.

شیء TransitOptions به صورت تحت‌اللفظی شامل فیلدهای زیر است:

{
  arrivalTime: Date,
  departureTime: Date,
  modes[]: TransitMode,
  routingPreference: TransitRoutePreference
}

این فیلدها در زیر توضیح داده شده‌اند:

  • arrivalTime ( اختیاری ) زمان مورد نظر برای رسیدن را به عنوان یک شیء Date مشخص می‌کند. اگر زمان رسیدن مشخص شود، زمان عزیمت نادیده گرفته می‌شود.
  • departureTime ( اختیاری ) زمان مورد نظر برای حرکت را به عنوان یک شیء Date مشخص می‌کند. در صورت مشخص شدن arrivalTime ، departureTime نادیده گرفته می‌شود. اگر هیچ مقداری برای departureTime یا arrivalTime مشخص نشود، به طور پیش‌فرض روی now (یعنی زمان فعلی) قرار می‌گیرد.
  • modes[] ( اختیاری ) آرایه‌ای است که شامل یک یا چند شیء TransitMode با حروف الفبا است. این فیلد فقط در صورتی می‌تواند گنجانده شود که درخواست شامل یک کلید API باشد. هر TransitMode یک حالت ترجیحی برای انتقال را مشخص می‌کند. مقادیر زیر مجاز هستند:
    • BUS نشان می‌دهد که مسیر محاسبه‌شده باید سفر با اتوبوس را ترجیح دهد.
    • RAIL نشان می‌دهد که مسیر محاسبه‌شده باید سفر با قطار، تراموا، قطار سبک شهری و مترو را ترجیح دهد.
    • SUBWAY نشان می‌دهد که مسیر محاسبه‌شده باید سفر با مترو را ترجیح دهد.
    • TRAIN نشان می‌دهد که مسیر محاسبه‌شده باید سفر با قطار را ترجیح دهد.
    • TRAM نشان می‌دهد که مسیر محاسبه‌شده باید سفر با تراموا و قطار سبک شهری را ترجیح دهد.
  • routingPreference ( اختیاری ) تنظیمات مربوط به مسیرهای ترانزیت را مشخص می‌کند. با استفاده از این گزینه، می‌توانید گزینه‌های برگشتی را به جای پذیرش بهترین مسیر پیش‌فرض انتخاب شده توسط API، تغییر دهید. این فیلد فقط در صورتی قابل تعیین است که درخواست شامل یک کلید API باشد. مقادیر زیر مجاز هستند:
    • FEWER_TRANSFERS نشان می‌دهد که مسیر محاسبه‌شده باید تعداد محدودی از انتقال‌ها را ترجیح دهد.
    • LESS_WALKING نشان می‌دهد که مسیر محاسبه‌شده باید میزان محدودی پیاده‌روی را ترجیح دهد.

یک نمونه DirectionsRequest از طریق ترانزیت در زیر نشان داده شده است:

{
  origin: 'Hoboken NJ',
  destination: 'Carroll Gardens, Brooklyn',
  travelMode: 'TRANSIT',
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: ['BUS'],
    routingPreference: 'FEWER_TRANSFERS'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

گزینه‌های رانندگی

شما می‌توانید گزینه‌های مسیریابی برای مسیرهای رانندگی را از طریق شیء DrivingOptions مشخص کنید.

شیء DrivingOptions شامل فیلدهای زیر است:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

این فیلدها در زیر توضیح داده شده‌اند:

  • departureTime ( برای اعتبار شیء drivingOptions به صورت تحت‌اللفظی مورد نیاز است ) زمان مطلوب حرکت را به عنوان یک شیء Date مشخص می‌کند. مقدار باید روی زمان فعلی یا زمانی در آینده تنظیم شود. نمی‌تواند در گذشته باشد. (API تمام تاریخ‌ها را به UTC تبدیل می‌کند تا از مدیریت یکپارچه در مناطق زمانی اطمینان حاصل شود.) برای مشتریان طرح پریمیوم پلتفرم نقشه‌های گوگل، اگر زمان departureTime در درخواست وارد کنید، API بهترین مسیر را با توجه به شرایط ترافیکی مورد انتظار در آن زمان برمی‌گرداند و زمان پیش‌بینی شده در ترافیک ( duration_in_traffic ) را در پاسخ لحاظ می‌کند. اگر زمان حرکت را مشخص نکنید (یعنی اگر درخواست شامل drivingOptions نباشد)، مسیر برگشتی بدون در نظر گرفتن شرایط ترافیکی، یک مسیر عموماً خوب است.
  • trafficModel ( اختیاری ) فرضیاتی را که هنگام محاسبه زمان حضور در ترافیک باید استفاده شوند، مشخص می‌کند. این تنظیم بر مقدار برگردانده شده در فیلد duration_in_traffic در پاسخ تأثیر می‌گذارد، که شامل زمان پیش‌بینی شده حضور در ترافیک بر اساس میانگین‌های تاریخی است. مقادیر پیش‌فرض bestguess هستند. مقادیر زیر مجاز هستند:
    • bestguess (پیش‌فرض) نشان می‌دهد که duration_in_traffic برگشتی باید بهترین تخمین زمان سفر با توجه به اطلاعات موجود در مورد شرایط ترافیکی تاریخی و ترافیک زنده باشد. ترافیک زنده هرچه departureTime به زمان حال نزدیک‌تر باشد، اهمیت بیشتری پیدا می‌کند.
    • pessimistic نشان می‌دهد که duration_in_traffic بازگشتی در ترافیک باید در بیشتر روزها بیشتر از زمان واقعی سفر باشد، هرچند گاهی اوقات روزهایی با شرایط ترافیکی بسیار بد ممکن است از این مقدار فراتر رود.
    • optimistic نشان می‌دهد که duration_in_traffic بازگشتی در ترافیک باید در بیشتر روزها کوتاه‌تر از زمان واقعی سفر باشد، هرچند گاهی اوقات در روزهایی که شرایط ترافیکی به خصوص خوبی دارند، ممکن است سریع‌تر از این مقدار باشد.

در زیر نمونه‌ای از درخواست مسیر رانندگی در فرم DirectionsRequest آمده است:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

سیستم‌های واحد

به طور پیش‌فرض، مسیرها با استفاده از سیستم واحد کشور یا منطقه مبدا محاسبه و نمایش داده می‌شوند. (توجه: مبداهایی که با استفاده از مختصات عرض/طول جغرافیایی به جای آدرس‌ها بیان می‌شوند، همیشه به طور پیش‌فرض از واحدهای متریک استفاده می‌کنند.) به عنوان مثال، مسیری از "شیکاگو، ایلینوی" به "تورنتو، ONT" نتایج را بر حسب مایل نمایش می‌دهد، در حالی که مسیر معکوس نتایج را بر حسب کیلومتر نمایش می‌دهد. می‌توانید با تنظیم صریح یک واحد در درخواست با استفاده از یکی از مقادیر UnitSystem زیر، این سیستم واحد را لغو کنید:

  • UnitSystem.METRIC نحوه‌ی استفاده از سیستم متریک را مشخص می‌کند. فواصل با استفاده از کیلومتر نشان داده می‌شوند.
  • UnitSystem.IMPERIAL استفاده از سیستم امپریال (انگلیسی) را مشخص می‌کند. فواصل با استفاده از مایل نشان داده می‌شوند.

نکته: این تنظیم سیستم واحد فقط روی متن نمایش داده شده به کاربر تأثیر می‌گذارد. نتیجه‌ی مسیرها همچنین شامل مقادیر مسافت است که به کاربر نشان داده نمی‌شود و همیشه بر حسب متر بیان می‌شوند.

بایاس منطقه‌ای برای جهت‌ها

سرویس مسیریابی API نقشه‌های گوگل، نتایج آدرسی را که تحت تأثیر دامنه (منطقه یا کشور) بارگذاری بوت‌استرپ جاوااسکریپت قرار دارند، برمی‌گرداند. (از آنجایی که اکثر کاربران https://maps.googleapis.com/ را بارگذاری می‌کنند، این یک دامنه ضمنی برای ایالات متحده تعیین می‌کند.) اگر بوت‌استرپ را از یک دامنه پشتیبانی‌شده متفاوت بارگذاری کنید، نتایجی که تحت تأثیر آن دامنه قرار دارند را دریافت خواهید کرد. به عنوان مثال، جستجو برای "سانفرانسیسکو" ممکن است نتایج متفاوتی را از برنامه‌هایی که https://maps.googleapis.com/ (ایالات متحده) را بارگذاری می‌کنند، نسبت به برنامه‌هایی که http://maps.google.es/ (اسپانیا) را بارگذاری می‌کنند، نشان دهد.

همچنین می‌توانید سرویس Directions را طوری تنظیم کنید که با استفاده از پارامتر region ، نتایجی را که به یک منطقه خاص گرایش دارند، برگرداند. این پارامتر یک کد منطقه را می‌گیرد که به عنوان یک زیربرچسب منطقه یونیکد دو کاراکتری (غیر عددی) مشخص می‌شود. در بیشتر موارد، این برچسب‌ها مستقیماً به مقادیر دو کاراکتری ccTLD ("دامنه سطح بالا") مانند "uk" در "co.uk" نگاشت می‌شوند. در برخی موارد، برچسب region از کدهای ISO-3166-1 نیز پشتیبانی می‌کند که گاهی اوقات با مقادیر ccTLD متفاوت هستند (به عنوان مثال "GB" برای "بریتانیای کبیر").

هنگام استفاده از پارامتر region :

  • فقط یک کشور یا منطقه را مشخص کنید. مقادیر چندگانه نادیده گرفته می‌شوند و می‌توانند منجر به درخواست ناموفق شوند.
  • فقط از زیربرچسب‌های ناحیه‌ای دو کاراکتری (با فرمت Unicode CLDR) استفاده کنید. سایر ورودی‌ها منجر به خطا خواهند شد.

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

مسیرهای رندرینگ

شروع یک درخواست جهت‌یابی به DirectionsService با متد route() نیازمند ارسال یک فراخوانی است که پس از تکمیل درخواست سرویس اجرا می‌شود. این فراخوانی یک کد DirectionsResult و یک کد DirectionsStatus را در پاسخ برمی‌گرداند.

وضعیت درخواست مسیرها

DirectionsStatus ممکن است مقادیر زیر را برگرداند:

  • OK نشان می‌دهد که پاسخ حاوی یک DirectionsResult معتبر است.
  • NOT_FOUND نشان می‌دهد که حداقل یکی از مکان‌های مشخص شده در مبدا، مقصد یا نقاط مسیر درخواست، قابلیت کدگذاری جغرافیایی ندارند.
  • ZERO_RESULTS نشان می‌دهد که هیچ مسیری بین مبدا و مقصد یافت نشد.
  • MAX_WAYPOINTS_EXCEEDED نشان می‌دهد که فیلدهای DirectionsWaypoint زیادی در DirectionsRequest ارائه شده است. به بخش زیر در مورد محدودیت‌های نقاط مسیر مراجعه کنید.
  • MAX_ROUTE_LENGTH_EXCEEDED نشان می‌دهد که مسیر درخواستی بسیار طولانی است و قابل پردازش نیست. این خطا زمانی رخ می‌دهد که مسیرهای پیچیده‌تری برگردانده می‌شوند. سعی کنید تعداد نقاط مسیر، پیچ‌ها یا دستورالعمل‌ها را کاهش دهید.
  • INVALID_REQUEST نشان می‌دهد که DirectionsRequest ارائه شده نامعتبر بوده است. شایع‌ترین دلایل این کد خطا، درخواست‌هایی هستند که مبدا یا مقصد را ندارند، یا درخواست حمل و نقلی است که شامل نقاط مسیر می‌شود.
  • OVER_QUERY_LIMIT نشان می‌دهد که صفحه وب درخواست‌های زیادی را در بازه زمانی مجاز ارسال کرده است.
  • REQUEST_DENIED نشان می‌دهد که صفحه وب مجاز به استفاده از سرویس جهت‌یابی نیست.
  • UNKNOWN_ERROR نشان می‌دهد که درخواست مسیر به دلیل خطای سرور قابل پردازش نیست. اگر دوباره امتحان کنید، ممکن است درخواست با موفقیت انجام شود.

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

نمایش نتیجه‌ی Directions

DirectionsResult شامل نتیجه‌ی کوئری جهت‌یابی است که می‌توانید خودتان آن را مدیریت کنید یا به یک شیء DirectionsRenderer ارسال کنید که می‌تواند به طور خودکار نمایش نتیجه روی نقشه را مدیریت کند.

برای نمایش یک DirectionsResult با استفاده از DirectionsRenderer ، باید موارد زیر را انجام دهید:

  1. یک شیء DirectionsRenderer ایجاد کنید.
  2. برای اتصال (bind) به نقشه ارسالی، تابع setMap() را روی رندرکننده فراخوانی کنید.
  3. تابع setDirections() را روی رندرکننده فراخوانی کنید و همانطور که در بالا ذکر شد، DirectionsResult را به آن منتقل کنید. از آنجا که رندرکننده یک MVCObject است، به طور خودکار هرگونه تغییر در ویژگی‌های خود را تشخیص داده و نقشه را هنگامی که جهت‌های مرتبط با آن تغییر کرده است، به‌روزرسانی می‌کند.

مثال زیر مسیرهای بین دو مکان در جاده ۶۶ را محاسبه می‌کند، که در آن مبدا و مقصد توسط مقادیر "start" و "end" داده شده در لیست‌های کشویی تنظیم شده‌اند. DirectionsRenderer نمایش چندخطی بین مکان‌های مشخص شده و قرار دادن نشانگرها در مبدا، مقصد و هر نقطه مسیر، در صورت لزوم، را مدیریت می‌کند.

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(result);
    }
  });
}

در بدنه HTML:

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

مشاهده مثال

مثال زیر مسیرهایی را با استفاده از روش‌های مختلف سفر بین هایت-اشبری تا اوشن بیچ در سانفرانسیسکو، کالیفرنیا نشان می‌دهد: 

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that JavaScript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

در بدنه HTML: 

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

مشاهده مثال

یک DirectionsRenderer نه تنها نمایش چندخطی و هر نشانگر مرتبط را مدیریت می‌کند، بلکه می‌تواند نمایش متنی جهت‌ها را نیز به صورت یک سری مراحل مدیریت کند. برای انجام این کار، setPanel() را در DirectionsRenderer خود فراخوانی کنید و <div> مورد نظر برای نمایش این اطلاعات را به آن منتقل کنید. انجام این کار همچنین تضمین می‌کند که اطلاعات حق چاپ مناسب و هرگونه هشداری را که ممکن است با نتیجه مرتبط باشد، نمایش می‌دهید.

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

مثال زیر مشابه مثال بالا است، اما شامل یک پنل <div> است که در آن مسیرها نمایش داده می‌شوند: 

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
  directionsRenderer.setPanel(document.getElementById('directionsPanel'));
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin:start,
    destination:end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

در بدنه HTML: 

<div id="map" style="float:left;width:70%;height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height:100%"></div>

مشاهده مثال

شیء DirectionsResult

هنگام ارسال درخواست جهت‌یابی به DirectionsService ، پاسخی شامل یک کد وضعیت و یک نتیجه دریافت می‌کنید که یک شیء DirectionsResult است. DirectionsResult یک شیء تحت‌اللفظی با فیلدهای زیر است:

  • geocoded_waypoints[] شامل آرایه‌ای از اشیاء DirectionsGeocodedWaypoint است که هر کدام حاوی جزئیاتی در مورد مختصات جغرافیایی مبدا، مقصد و نقاط مسیر هستند.
  • routes[] شامل آرایه‌ای از اشیاء DirectionsRoute است. هر مسیر، راهی برای رسیدن از مبدا به مقصد ارائه شده در DirectionsRequest را نشان می‌دهد. به طور کلی، فقط یک مسیر برای هر درخواست داده شده بازگردانده می‌شود، مگر اینکه فیلد provideRouteAlternatives درخواست روی true تنظیم شده باشد، که در آن، ممکن است چندین مسیر بازگردانده شوند.

نکته: ویژگی via_waypoint در مسیرهای جایگزین منسوخ شده است. نسخه ۳.۲۷ آخرین نسخه از API است که نقاط مسیر via اضافی را در مسیرهای جایگزین اضافه می‌کند. برای نسخه‌های ۳.۲۸ و بالاتر از API، می‌توانید با غیرفعال کردن کشیدن مسیرهای جایگزین، به پیاده‌سازی مسیرهای قابل کشیدن با استفاده از سرویس Directions ادامه دهید. فقط مسیر اصلی باید قابل کشیدن باشد. کاربران می‌توانند مسیر اصلی را تا زمانی که با یک مسیر جایگزین مطابقت داشته باشد، بکشید.

مسیرها، نقاط مسیر با کد جغرافیایی

یک DirectionsGeocodedWaypoint شامل جزئیاتی در مورد مختصات جغرافیایی مبدا، مقصد و نقاط مسیر است.

DirectionsGeocodedWaypoint یک شیء تحت‌اللفظی با فیلدهای زیر است:

  • geocoder_status کد وضعیتی را نشان می‌دهد که از عملیات geocoding حاصل شده است. این فیلد می‌تواند شامل مقادیر زیر باشد.
    • "OK" نشان می‌دهد که هیچ خطایی رخ نداده است؛ آدرس با موفقیت تجزیه شده و حداقل یک کد جغرافیایی بازگردانده شده است.
    • "ZERO_RESULTS" نشان می‌دهد که کد جغرافیایی موفقیت‌آمیز بوده اما هیچ نتیجه‌ای برنگردانده است. این ممکن است در صورتی رخ دهد که به کد جغرافیایی یک address ناموجود داده شده باشد.

  • partial_match نشان می‌دهد که geocoder تطابق دقیقی برای درخواست اصلی برنگردانده است، اگرچه توانسته بخشی از آدرس درخواستی را مطابقت دهد. شما می‌توانید درخواست اصلی را از نظر غلط املایی و/یا آدرس ناقص بررسی کنید.

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

  • place_id یک شناسه منحصر به فرد برای یک مکان است که می‌تواند با سایر APIهای گوگل مورد استفاده قرار گیرد. برای مثال، می‌توانید از place_id با کتابخانه Google Places API برای دریافت جزئیات یک کسب و کار محلی، مانند شماره تلفن، ساعات کاری، نظرات کاربران و موارد دیگر استفاده کنید. به نمای کلی شناسه مکان مراجعه کنید.
  • types[] آرایه‌ای است که نوع نتیجه‌ی برگردانده شده را نشان می‌دهد. این آرایه شامل مجموعه‌ای از صفر یا چند برچسب است که نوع ویژگی برگردانده شده در نتیجه را مشخص می‌کند. برای مثال، یک کد جغرافیایی از "شیکاگو" "محلی" را برمی‌گرداند که نشان می‌دهد "شیکاگو" یک شهر است و همچنین "سیاسی" را برمی‌گرداند که نشان می‌دهد یک نهاد سیاسی است.

مسیرها

نکته : شیء قدیمی DirectionsTrip به DirectionsRoute تغییر نام داده است. توجه داشته باشید که یک مسیر اکنون به کل سفر از ابتدا تا انتها اشاره دارد، نه صرفاً یک بخش از سفر والد.

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

DirectionsRoute یک شیء تحت‌اللفظی با فیلدهای زیر است:

  • legs[] شامل آرایه‌ای از اشیاء DirectionsLeg است که هر کدام حاوی اطلاعاتی در مورد یک شاخه از مسیر، از دو مکان در مسیر داده شده، هستند. برای هر نقطه مسیر یا مقصد مشخص شده، یک شاخه جداگانه وجود خواهد داشت. (مسیری که هیچ نقطه مسیر نداشته باشد، دقیقاً شامل یک DirectionsLeg خواهد بود.) هر شاخه از مجموعه‌ای از DirectionStep ها تشکیل شده است.
  • waypoint_order شامل آرایه‌ای است که ترتیب هر نقطه‌ی مسیر در مسیر محاسبه‌شده را نشان می‌دهد. اگر به DirectionsRequest مقدار optimizeWaypoints: true داده شود، این آرایه ممکن است ترتیب تغییر یافته‌ای داشته باشد.
  • overview_path شامل آرایه‌ای از LatLng ها است که یک مسیر تقریبی (هموار شده) از جهت‌های حاصل را نشان می‌دهند.
  • overview_polyline شامل یک شیء تک points است که یک نمایش چندخطی کدگذاری شده از مسیر را در خود نگه می‌دارد. این چندخطی یک مسیر تقریبی (هموار شده) از جهت‌های حاصل است.
  • bounds شامل یک LatLngBounds است که مرزهای چندخطی را در امتداد این مسیر مشخص نشان می‌دهد.
  • copyrights شامل متن کپی‌رایت برای نمایش در این مسیر هستند.
  • warnings[] شامل آرایه‌ای از هشدارها است که هنگام نمایش این دستورالعمل‌ها نمایش داده می‌شوند. اگر از شیء DirectionsRenderer ارائه شده استفاده نمی‌کنید، باید خودتان این هشدارها را مدیریت و نمایش دهید.
  • fare شامل کل کرایه (یعنی کل هزینه‌های بلیط) در این مسیر است. این ویژگی فقط برای درخواست‌های حمل و نقل عمومی و فقط برای مسیرهایی که اطلاعات کرایه برای همه مراحل حمل و نقل عمومی در دسترس است، بازگردانده می‌شود. این اطلاعات شامل موارد زیر است:
    • currency : یک کد ارزی ISO 4217 که نشان دهنده ارزی است که مبلغ بر حسب آن بیان می‌شود.
    • value : مبلغ کل کرایه، به ارزی که در بالا مشخص شده است.

پاها

نکته : شیء قدیمی DirectionsRoute DirectionsLeg تغییر نام داده است.

یک DirectionsLeg یک بخش از سفر از مبدا به مقصد را در مسیر محاسبه‌شده تعریف می‌کند. برای مسیرهایی که هیچ نقطه‌ی بین‌راهی ندارند، مسیر شامل یک «بخش» خواهد بود، اما برای مسیرهایی که یک یا چند نقطه‌ی بین‌راهی را تعریف می‌کنند، مسیر شامل یک یا چند بخش خواهد بود که مربوط به بخش‌های خاص سفر است.

DirectionsLeg یک شیء تحت‌اللفظی با فیلدهای زیر است:

  • steps[] شامل آرایه‌ای از اشیاء DirectionsStep است که اطلاعات مربوط به هر مرحله جداگانه از مسیر را نشان می‌دهد.

  • distance نشان دهنده کل مسافت طی شده توسط این پایه است، به عنوان یک شیء Distance به شکل زیر:

    • value فاصله را بر حسب متر نشان می‌دهد
    • text شامل یک رشته نمایش فاصله است که به طور پیش‌فرض در واحدهایی که در مبدا استفاده می‌شوند نمایش داده می‌شود. (به عنوان مثال، مایل برای هر مبدا در ایالات متحده استفاده خواهد شد.) شما می‌توانید با تنظیم خاص یک UnitSystem در پرس و جوی اصلی، این سیستم واحد را لغو کنید. توجه داشته باشید که صرف نظر از سیستم واحدی که استفاده می‌کنید، فیلد distance.value همیشه حاوی مقداری است که بر حسب متر بیان می‌شود.

    اگر فاصله نامعلوم باشد، این فیلدها ممکن است تعریف نشده باشند.

  • duration کل مدت زمان این مرحله را نشان می‌دهد، به عنوان یک شیء Duration به شکل زیر:

    • value مدت زمان را بر حسب ثانیه نشان می‌دهد.
    • text شامل یک رشته است که مدت زمان را نشان می‌دهد.

    اگر مدت زمان نامشخص باشد، این فیلدها ممکن است تعریف نشده باشند.

  • duration_in_traffic مدت زمان کل این مرحله را با در نظر گرفتن شرایط ترافیک فعلی نشان می‌دهد. duration_in_traffic فقط در صورتی برگردانده می‌شود که همه موارد زیر صحیح باشند:

    • این درخواست شامل نقاط بین‌راهی توقفگاه نمی‌شود. یعنی، شامل نقاط بین‌راهی که stopover در آنها true است، نمی‌شود.
    • این درخواست به‌طور خاص برای مسیرهای رانندگی است— mode روی driving تنظیم شده است.
    • زمان departureTime به عنوان بخشی از فیلد drivingOptions در درخواست گنجانده شده است.
    • شرایط ترافیکی برای مسیر مورد نظر فراهم است.

    تابع duration_in_traffic شامل فیلدهای زیر است:

    • value مدت زمان را بر حسب ثانیه نشان می‌دهد.
    • text شامل نمایشی قابل خواندن توسط انسان از مدت زمان است.
  • arrival_time شامل زمان تخمینی رسیدن برای این مرحله است. این ویژگی فقط برای مسیرهای حمل و نقل برگردانده می‌شود. نتیجه به صورت یک شیء Time با سه ویژگی برگردانده می‌شود:
    • زمان مشخص شده را به عنوان یک شیء Date جاوا اسکریپت value .
    • زمان مشخص شده را به صورت رشته‌ای text . زمان در منطقه زمانی ایستگاه حمل و نقل عمومی نمایش داده می‌شود.
    • time_zone شامل منطقه زمانی این ایستگاه است. مقدار، نام منطقه زمانی تعریف شده در پایگاه داده منطقه زمانی IANA است، مثلاً "America/New_York".
  • departure_time شامل زمان تخمینی حرکت برای این مرحله است که به عنوان یک شیء Time مشخص شده است. زمان departure_time فقط برای مسیرهای حمل و نقل عمومی در دسترس است.
  • start_location شامل LatLng مبدا این بخش است. از آنجا که سرویس وب Directions با استفاده از نزدیکترین گزینه حمل و نقل (معمولاً یک جاده) در نقاط شروع و پایان، مسیرهای بین مکان‌ها را محاسبه می‌کند، start_location ممکن است با مبدا ارائه شده برای این بخش متفاوت باشد، اگر، برای مثال، جاده‌ای در نزدیکی مبدا نباشد.
  • end_location شامل LatLng مقصد این مرحله است. از آنجا که DirectionsService با استفاده از نزدیکترین گزینه حمل و نقل (معمولاً یک جاده) در نقاط شروع و پایان، مسیرهای بین مکان‌ها را محاسبه می‌کند، end_location ممکن است با مقصد ارائه شده برای این مرحله متفاوت باشد، اگر، برای مثال، جاده‌ای در نزدیکی مقصد نباشد.
  • start_address شامل آدرس قابل خواندن توسط انسان (معمولاً آدرس خیابان) از ابتدای این بخش است.

    این محتوا باید به همان شکلی که هست خوانده شود. آدرس فرمت شده را به صورت برنامه‌نویسی تجزیه نکنید.
  • end_address شامل آدرس قابل خواندن توسط انسان (معمولاً آدرس خیابان) انتهای این شاخه است.

    این محتوا باید به همان شکلی که هست خوانده شود. آدرس فرمت شده را به صورت برنامه‌نویسی تجزیه نکنید.

مسیرها مراحل

یک DirectionsStep ، جزئی‌ترین واحد مسیر یک جهت است که شامل یک مرحله است که یک دستورالعمل خاص و واحد را در سفر توصیف می‌کند. به عنوان مثال، "در خیابان چهارم غربی به چپ بپیچید". این مرحله نه تنها دستورالعمل را توصیف می‌کند، بلکه شامل اطلاعات مسافت و مدت زمان مربوط به نحوه ارتباط این مرحله با مرحله بعدی نیز می‌شود. به عنوان مثال، مرحله‌ای که با عنوان "ورود به I-80 غربی" مشخص شده است، ممکن است شامل مدت زمان "37 مایل" و "40 دقیقه" باشد که نشان می‌دهد مرحله بعدی 37 مایل/40 دقیقه از این مرحله فاصله دارد.

هنگام استفاده از سرویس Directions برای جستجوی مسیرهای حمل و نقل عمومی، آرایه steps شامل اطلاعات خاص حمل و نقل عمومی اضافی در قالب یک شیء transit خواهد بود. اگر مسیرها شامل چندین حالت حمل و نقل باشند، مسیرهای دقیق برای مسیرهای پیاده‌روی یا رانندگی در آرایه steps[] ارائه می‌شود. به عنوان مثال، یک مسیر پیاده‌روی شامل مسیرهایی از مکان‌های شروع و پایان خواهد بود: "به سمت خیابان اینس و خیابان فیچ پیاده‌روی کنید". آن مسیر شامل مسیرهای دقیق پیاده‌روی برای آن مسیر در آرایه steps[] خواهد بود، مانند: "به سمت شمال غربی بروید"، "به سمت چپ به سمت خیابان آرلیوس بپیچید" و "به سمت چپ به سمت خیابان اینس بپیچید".

DirectionsStep یک شیء تحت‌اللفظی با فیلدهای زیر است:

  • instructions شامل دستورالعمل‌هایی برای این مرحله در یک رشته متنی است.
  • distance شامل مسافت طی شده توسط این مرحله تا مرحله بعدی، به عنوان یک شیء Distance است. (به توضیحات موجود در DirectionsLeg در بالا مراجعه کنید.) اگر مسافت ناشناخته باشد، این فیلد ممکن است تعریف نشده باشد.
  • duration شامل تخمینی از زمان مورد نیاز برای انجام مرحله، تا مرحله بعدی، به عنوان یک شیء Duration است. (به توضیحات موجود در DirectionsLeg در بالا مراجعه کنید.) اگر مدت زمان ناشناخته باشد، این فیلد ممکن است تعریف نشده باشد.
  • start_location شامل LatLng جغرافیایی نقطه شروع این مرحله است.
  • end_location شامل LatLng نقطه پایان این مرحله است.
  • polyline شامل یک شیء تک points است که نمایش چندخطی کدگذاری‌شده از مرحله را در خود نگه می‌دارد. این چندخطی یک مسیر تقریبی (هموار شده) از مرحله است.
  • steps[] یک شیء با حروف الفبای DirectionsStep که شامل دستورالعمل‌های دقیق برای قدم‌های پیاده‌روی یا رانندگی در مسیرهای حمل و نقل عمومی است. زیرمراحل فقط برای مسیرهای حمل و نقل عمومی در دسترس هستند.
  • travel_mode شامل TravelMode مورد استفاده در این مرحله است. مسیرهای حمل و نقل عمومی ممکن است ترکیبی از مسیرهای پیاده‌روی و حمل و نقل عمومی باشند.
  • path شامل آرایه‌ای از LatLngs است که مسیر این مرحله را توصیف می‌کنند.
  • transit شامل اطلاعات خاص حمل و نقل عمومی، مانند زمان ورود و خروج و نام خط حمل و نقل عمومی است.

اطلاعات ویژه حمل و نقل عمومی

Transit directions return additional information that is not relevant for other modes of transportation. These additional properties are exposed through the TransitDetails object, returned as a property of DirectionsStep . From the TransitDetails object you can access additional information for the TransitStop , TransitLine , TransitAgency , and VehicleType objects as described below.

Transit Details

The TransitDetails object exposes the following properties:

  • arrival_stop contains a TransitStop object representing the arrival station/stop with the following properties:
    • name the name of the transit station/stop. eg. "Union Square".
    • location the location of the transit station/stop, represented as a LatLng .
  • departure_stop contains a TransitStop object representing the departure station/stop.
  • arrival_time contains the arrival time, specified as a Time object with three properties:
    • value the time specified as a JavaScript Date object.
    • text the time specified as a string. The time is displayed in the time zone of the transit stop.
    • time_zone contains the time zone of this station. The value is the name of the time zone as defined in the IANA Time Zone Database , eg "America/New_York".
  • departure_time contains the departure time, specified as a Time object.
  • headsign specifies the direction in which to travel on this line, as it is marked on the vehicle or at the departure stop. This will often be the terminus station.
  • headway when available, this specifies the expected number of seconds between departures from the same stop at this time. For example, with a headway value of 600, you would expect a ten minute wait if you should miss your bus.
  • line contains a TransitLine object literal that contains information about the transit line used in this step. The TransitLine provides the name and operator of the line, along with other properties described in the TransitLine reference documentation.
  • num_stops contains the number of stops in this step. Includes the arrival stop, but not the departure stop. For example, if your directions involve leaving from Stop A, passing through stops B and C, and arriving at stop D, num_stops will return 3.

Transit Line

The TransitLine object exposes the following properties:

  • name contains the full name of this transit line. eg. "7 Avenue Express" or "14th St Crosstown".
  • short_name contains the short name of this transit line. This will normally be a line number, such as "2" or "M14".
  • agencies is an array containing a single TransitAgency object. The TransitAgency object provides information about the operator of this line, including the following properties:
    • name contains the name of the transit agency.
    • phone contains the phone number of the transit agency.
    • url contains the URL for the transit agency.

    Note : If you are rendering transit directions manually instead of using the DirectionsRenderer object, you must display the names and URLs of the transit agencies servicing the trip results.

  • url contains a URL for this transit line as provided by the transit agency.
  • icon contains a URL for the icon associated with this line. Most cities will use generic icons that vary by the type of vehicle. Some transit lines, such as the New York subway system, have icons specific to that line.
  • color contains the color commonly used in signage for this transit. The color will be specified as a hex string such as: #FF0033.
  • text_color contains the color of text commonly used for signage of this line. The color will be specified as a hex string.
  • vehicle contains a Vehicle object that includes the following properties:
    • name contains the name of the vehicle on this line. eg. "Subway."
    • type contains the type of vehicle used on this line. See the Vehicle Type documentation for a complete list of supported values.
    • icon contains a URL for the icon commonly associated with this vehicle type.
    • local_icon contains the URL for the icon associated with this vehicle type, based on the local transport signage.

نوع خودرو

The VehicleType object exposes the following properties:

ارزش تعریف
VehicleType.RAIL Rail.
VehicleType.METRO_RAIL Light rail transit.
VehicleType.SUBWAY Underground light rail.
VehicleType.TRAM Above ground light rail.
VehicleType.MONORAIL Monorail.
VehicleType.HEAVY_RAIL Heavy rail.
VehicleType.COMMUTER_TRAIN Commuter rail.
VehicleType.HIGH_SPEED_TRAIN High speed train.
VehicleType.BUS اتوبوس.
VehicleType.INTERCITY_BUS Intercity bus.
VehicleType.TROLLEYBUS Trolleybus.
VehicleType.SHARE_TAXI Share taxi is a kind of bus with the ability to drop off and pick up passengers anywhere on its route.
VehicleType.FERRY Ferry.
VehicleType.CABLE_CAR A vehicle that operates on a cable, usually on the ground. Aerial cable cars may be of the type VehicleType.GONDOLA_LIFT .
VehicleType.GONDOLA_LIFT An aerial cable car.
VehicleType.FUNICULAR A vehicle that is pulled up a steep incline by a cable. A Funicular typically consists of two cars, with each car acting as a counterweight for the other.
VehicleType.OTHER All other vehicles will return this type.

Inspecting DirectionsResults

The DirectionsResults components — DirectionsRoute , DirectionsLeg , DirectionsStep and TransitDetails — may be inspected and used when parsing any directions response.

Important : If you are rendering transit directions manually instead of using the DirectionsRenderer object, you must display the names and URLs of the transit agencies servicing the trip results.

The following example plots walking directions to certain tourist attractions in New York City. We inspect the route's DirectionsStep to add markers for each step, and attach information to an InfoWindow with instructional text for that step.

Note : Since we are calculating walking directions, we also display any warnings to the user in a separate <div> panel. 

var map;
var directionsRenderer;
var directionsService;
var stepDisplay;
var markerArray = [];

function initMap() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsRenderer = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
      origin: start,
      destination: end,
      travelMode: 'WALKING'
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsRenderer.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

In the HTML body: 

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

View example

Using Waypoints in Routes

As noted within the DirectionsRequest , you may also specify waypoints (of type DirectionsWaypoint ) when calculating routes using the Directions service for walking, bicycling or driving directions. Waypoints are not available for transit directions. Waypoints allow you to calculate routes through additional locations, in which case the returned route passes through the given waypoints.

A waypoint consists of the following fields:

  • location (required) specifies the address of the waypoint.
  • stopover (optional) indicates whether this waypoint is a actual stop on the route ( true ) or instead only a preference to route through the indicated location ( false ). Stopovers are true by default.

By default, the Directions service calculates a route through the provided waypoints in their given order. Optionally, you may pass optimizeWaypoints: true within the DirectionsRequest to allow the Directions service to optimize the provided route by rearranging the waypoints in a more efficient order. (This optimization is an application of the traveling salesperson problem .) Travel time is the primary factor which is optimized, but other factors such as distance, number of turns and many more may be taken into account when deciding which route is the most efficient. All waypoints must be stopovers for the Directions service to optimize their route.

If you instruct the Directions service to optimize the order of its waypoints, their order will be returned in the waypoint_order field within the DirectionsResult object.

The following example calculates cross-country routes across the United States using a variety of start points, end points, and waypoints. (To select multiple waypoints, press Ctrl-Click when selecting items within the list.) Note that we inspect the routes.start_address and routes.end_address to provide us with the text for each route's start and end point.

تایپ اسکریپت 

function initMap(): void {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 6,
      center: { lat: 41.85, lng: -87.65 },
    }
  );

  directionsRenderer.setMap(map);

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      calculateAndDisplayRoute(directionsService, directionsRenderer);
    }
  );
}

function calculateAndDisplayRoute(
  directionsService: google.maps.DirectionsService,
  directionsRenderer: google.maps.DirectionsRenderer
) {
  const waypts: google.maps.DirectionsWaypoint[] = [];
  const checkboxArray = document.getElementById(
    "waypoints"
  ) as HTMLSelectElement;

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: (checkboxArray[i] as HTMLOptionElement).value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: (document.getElementById("start") as HTMLInputElement).value,
      destination: (document.getElementById("end") as HTMLInputElement).value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById(
        "directions-panel"
      ) as HTMLElement;

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance!.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

جاوا اسکریپت 

function initMap() {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 6,
    center: { lat: 41.85, lng: -87.65 },
  });

  directionsRenderer.setMap(map);
  document.getElementById("submit").addEventListener("click", () => {
    calculateAndDisplayRoute(directionsService, directionsRenderer);
  });
}

function calculateAndDisplayRoute(directionsService, directionsRenderer) {
  const waypts = [];
  const checkboxArray = document.getElementById("waypoints");

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: document.getElementById("start").value,
      destination: document.getElementById("end").value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById("directions-panel");

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

window.initMap = initMap;
index.js

Limits and Restrictions for Waypoints

The following usage limits and restrictions apply:

  • The maximum number of waypoints allowed when using the Directions service in the Maps JavaScript API is 25, plus the origin and destination. The limits are the same for the Directions API (Legacy) web service .
  • For the Directions API (Legacy) web service , customers are allowed 25 waypoints, plus the origin, and destination.
  • Google Maps Platform Premium Plan customers are allowed 25 waypoints, plus the origin, and destination.
  • Waypoints are not supported for transit directions.

Draggable Directions

Users may modify cycling, walking or driving directions displayed using a DirectionsRenderer dynamically if they are draggable , allowing a user to select and alter routes by clicking and dragging the resulting paths on the map. You indicate whether a renderer's display allows draggable directions by setting its draggable property to true . Transit directions cannot be made draggable.

When directions are draggable, a user may select any point on the path (or waypoint) of the rendered result and move the indicated component to a new location. The DirectionsRenderer will dynamically update to show the modified path. Upon release, a transitional waypoint will be added to the map (indicated by a small white marker). Selecting and moving a path segment will alter that leg of the route, while selecting and moving a waypoint marker (including start and end points) will alter the legs of the route passing through that waypoint.

Because draggable directions are modified and rendered client-side, you may wish to monitor and handle the directions_changed event on the DirectionsRenderer to be notified when the user has modified the displayed directions.

The following code shows a trip from Perth on the west coast of Australia to Sydney on the east coast. The code monitors the directions_changed event to update the total distance of all legs of the journey.

تایپ اسکریپت 

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -24.345, lng: 134.46 }, // Australia.
    }
  );

  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel") as HTMLElement,
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });

  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(
  origin: string,
  destination: string,
  service: google.maps.DirectionsService,
  display: google.maps.DirectionsRenderer
) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result: google.maps.DirectionsResult) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result: google.maps.DirectionsResult) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i]!.distance!.value;
  }

  total = total / 1000;
  (document.getElementById("total") as HTMLElement).innerHTML = total + " km";
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

جاوا اسکریپت 

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -24.345, lng: 134.46 }, // Australia.
  });
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel"),
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });
  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer,
  );
}

function displayRoute(origin, destination, service, display) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }

  total = total / 1000;
  document.getElementById("total").innerHTML = total + " km";
}

window.initMap = initMap;
index.js
View example

Try Sample