خدمة الاتجاهات

نظرة عامة

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

عند تحديد المصدر أو الوجهة في طلب الاتجاهات، يمكنك تحديد سلسلة طلب بحث (على سبيل المثال، "شيكاغو، إلينوي" أو "القاهرة، جنوب سيناء"، أو قيمة LatLng، أو عنصر Place.

يمكن لخدمة "الاتجاهات" عرض اتجاهات متعددة الأجزاء باستخدام سلسلة من نقاط الطريق. يتم عرض الاتجاهات على شكل خطوط متعدّدة ترسم المسار على خريطة، أو أيضًا كسلسلة من الأوصاف النصية ضمن العنصر <div> (على سبيل المثال، "الاتجاه يمينًا إلى منحدر جسر ويليامزبورغ").

البدء

قبل استخدام خدمة "الاتجاهات" في واجهة برمجة تطبيقات JavaScript للخرائط، تأكَّد أولاً من تفعيل واجهة برمجة التطبيقات Directions API في Google Cloud Console ضمن المشروع نفسه الذي أعددته لـ Maps JavaScript API.

للاطّلاع على قائمة واجهات برمجة التطبيقات المفعَّلة:

  1. انتقِل إلى Google Cloud Console.
  2. انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط وانقر على فتح.
  3. من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Directions API.
  4. إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك جاهز. إذا لم تكن واجهة برمجة التطبيقات مدرَجة، يمكنك تفعيلها:
    1. في أعلى الصفحة، انقر على ENABLE API لعرض علامة تبويب المكتبة. ويمكنك بدلاً من ذلك اختيار المكتبة من القائمة الجانبية اليمنى.
    2. ابحث عن Directions API، ثم اختَرها من قائمة النتائج.
    3. انقر على تفعيل. عند انتهاء العملية، تظهر Directions API في قائمة واجهات برمجة التطبيقات في لوحة البيانات.

الأسعار والسياسات

السعر

اعتبارًا من 16 تموز (يوليو) 2018، دخلت خطة التسعير الجديدة "الدفع حسب الاستخدام" حيز التنفيذ في "خرائط Google" و"المسارات" و"الأماكن". للحصول على مزيد من المعلومات حول الأسعار الجديدة وحدود الاستخدام لاستخدام خدمة JavaScript Directions، يمكنك الاطّلاع على الاستخدام والفوترة لواجهة برمجة تطبيقات Directions.

السياسات

ويجب أن يتوافق استخدام خدمة Directions مع السياسات الموضّحة في Directions API.

طلبات الاتجاهات

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

لاستخدام الاتجاهات في Maps JavaScript API، أنشِئ كائنًا من النوع DirectionsService واستدعِ DirectionsService.route() لبدء طلب لخدمة الاتجاهات، مع تمريره حرفيًا كائن DirectionsRequest يحتوي على عبارات الإدخال وطريقة استدعاء لتنفيذها عند استلام الردّ.

يحتوي العنصر الحرفي 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 (على سبيل المثال، "Chicago, IL") أو على أنّها قيمة LatLng أو كعنصر Place. إذا كنت تستخدم كائن Place، يمكنك تحديد رقم تعريف مكان أو سلسلة طلب بحث أو موقع جغرافي LatLng. يمكنك استرداد أرقام تعريف الأماكن من خدمات "الترميز الجغرافي" و"بحث عن الأماكن" و"الإكمال التلقائي عن الأماكن" في واجهة برمجة تطبيقات JavaScript للخرائط. للحصول على مثال لاستخدام أرقام تعريف الأماكن من ميزة "الإكمال التلقائي" الخاصة بالأماكن، يُرجى الاطّلاع على الإكمال التلقائي عن المكان والاتجاهات.
  • destination (مطلوبة) تحدّد موقع النهاية الذي يجب حساب الاتجاهات إليه. تتطابق الخيارات مع الحقل origin الموضّح أعلاه.
  • travelMode (مطلوبة) تحدّد وسيلة النقل التي يجب استخدامها عند احتساب الاتجاهات. ويتم تحديد القيم الصالحة في أوضاع السفر أدناه.
  • تحدّد السمة transitOptions (اختيارية) قيمًا تنطبق فقط على الطلبات التي تكون travelMode فيها قيمة TRANSIT. ويمكن الاطّلاع على القيم الصالحة في قسم خيارات النقل العام أدناه.
  • تحدّد السمة drivingOptions (اختيارية) قيمًا تنطبق فقط على الطلبات التي تكون travelMode فيها قيمة DRIVING. ويتم توضيح القيم الصالحة في خيارات القيادة أدناه.
  • unitSystem (اختيارية) تحدّد نظام الوحدات المطلوب استخدامه عند عرض النتائج. تم تحديد القيم الصالحة في Unit Systems أدناه.

  • تحدّد waypoints[] (اختيارية) مصفوفة من DirectionsWaypoint. وتعدّل نقاط الطريق المسار من خلال توجيهها عبر المواقع الجغرافية المحدّدة. ويتم تحديد نقطة الطريق ككائن حرفي مع الحقول الموضّحة أدناه:

    • تحدّد السمة location موقع النقطة الوسيطة، على أنّها LatLng، على أنّها كائن مكان، أو كعنصر String سيتم ترميزه جغرافيًا.
    • stopover هي قيمة منطقية تشير إلى أنّ نقطة الطريق هي محطة على المسار، ما يؤثر في تقسيم المسار إلى مسارَين.

    (لمزيد من المعلومات حول نقاط الطريق، راجع استخدام نقاط الطرق في المسارات أدناه).

  • optimizeWaypoints (اختيارية) تحدّد أنّه يمكن تحسين المسار الذي يستخدم waypoints من خلال إعادة ترتيب نقاط الطريق بترتيب أكثر فعالية. إذا كان true، ستعرض خدمة "الاتجاهات" waypoints التي تمت إعادة ترتيبها في الحقل waypoint_order.(لمزيد من المعلومات، يُرجى الاطّلاع على استخدام نقاط الطرق في المسارات أدناه).
  • وتشير السمة provideRouteAlternatives (اختيارية) عند ضبطها على true إلى أنّ خدمة الاتجاهات قد توفّر أكثر من مسار بديل واحد في الاستجابة. ويُرجى العِلم بأنّ توفير بدائل للمسارات قد يزيد من وقت الاستجابة من الخادم. لا يتوفر هذا إلا للطلبات التي لا تحتوي على نقاط وسيطة.
  • تشير السمة avoidFerries (اختيارية) عند ضبطها على true إلى أنّه يجب على المسارات المحسوبة تجنُّب العبّارات، إن أمكن.
  • إنّ avoidHighways (اختيارية) عند الضبط على true تشير إلى أنّ المسارات المحسوبة يجب أن تتجنّب الطرق السريعة الرئيسية، إن أمكن.
  • تشير السمة avoidTolls (اختيارية) عند ضبطها على true إلى أنّه يجب تجنّب الطرق التي يتم احتسابها برسوم عبور، إن أمكن.
  • region (اختيارية) تحدّد رمز المنطقة، الذي يتم تحديده كقيمة مكوّنة من حرفَين ("نطاق المستوى الأعلى") الذي يتم ترميزه حسب البلد (ccTLD). (لمزيد من المعلومات، راجع انحياز المنطقة أدناه).

في ما يلي نموذج عن 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" اتجاهات المشي عبر مسارات المشاة والأرصفة.

يمكنك الرجوع إلى تفاصيل تغطية "منصة خرائط Google" لتحديد إلى أي مدى يتيح البلد استخدام الاتجاهات. إذا طلبت الاتجاهات لمنطقة لا يتوفّر فيها نوع الاتجاه هذا، ستعرض الاستجابة DirectionsStatus="ZERO_RESULTS".

ملاحظة: قد لا تشتمل اتجاهات المشي على مسارات واضحة للمشاة، لذا ستعرض اتجاهات المشي تحذيرات في DirectionsResult. ويجب عرض هذه التحذيرات دائمًا للمستخدم. في حال عدم استخدام DirectionsRenderer التلقائية، تقع على عاتقك مسؤولية ضمان عرض التحذيرات.

خيارات النقل العام

تختلف الخيارات المتاحة لطلب الاتجاهات بين وسائل النقل. عند طلب اتجاهات النقل العام، سيتم تجاهل الخيارات avoidHighways وavoidTolls وwaypoints[] وoptimizeWaypoints. يمكنك تحديد خيارات التوجيه المتعلّقة بالنقل العام من خلال العنصر TransitOptions الحرفي.

تكون اتجاهات النقل العام حسّاسة من حيث التوقيت. سيتم عرض الاتجاهات فقط لأوقات في المستقبل.

يتضمّن العنصر TransitOptions الحرفي الحقول التالية:

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

في ما يلي شرح لهذه الحقول:

  • تحدّد السمة arrivalTime (اختيارية) وقت الوصول المطلوب ككائن Date. وفي حال تحديد وقت الوصول، يتم تجاهل وقت المغادرة.
  • تحدّد السمة departureTime (اختيارية) وقت المغادرة المطلوب كعنصر Date. وسيتم تجاهل departureTime في حال تحديد arrivalTime. الإعداد التلقائي هو الآن (أي الوقت الحالي) إذا لم يتم تحديد أي قيمة لـ departureTime أو arrivalTime.
  • modes[] (اختيارية) هي مصفوفة تحتوي على قيمة حرفية واحدة أو أكثر لكائن TransitMode. لا يمكن تضمين هذا الحقل إلّا إذا كان الطلب يتضمّن مفتاح واجهة برمجة التطبيقات. تحدّد كل سمة TransitMode وسيلة نقل مفضَّلة. يُسمح باستخدام القيم التالية:
    • تشير السمة BUS إلى أنّ المسار المحسوب يجب أن يفضّل السفر بالحافلة.
    • تشير السمة RAIL إلى أنّ المسار المحسوب يجب أن يُفضّل التنقّل بالقطار أو الترام أو القطار الخفيف أو مترو الأنفاق.
    • تشير السمة SUBWAY إلى أنّ المسار المحسوب يجب أن يُفضِّل السفر باستخدام مترو الأنفاق.
    • تشير السمة TRAIN إلى أنّ المسار المحسوب يجب أن يفضّل السفر بالقطار.
    • تشير السمة TRAM إلى أنّ المسار المحسوب يجب أن يُفضّل السفر باستخدام الترام والقطارات الخفيفة.
  • routingPreference (اختيارية) تحدّد الإعدادات المفضّلة لمسارات النقل العام. وباستخدام هذا الخيار، يمكنك الانحياز للخيارات المعروضة، بدلاً من قبول أفضل مسار تلقائي يتم اختياره من خلال واجهة برمجة التطبيقات. لا يمكن تحديد هذا الحقل إلّا إذا كان الطلب يتضمّن مفتاح واجهة برمجة التطبيقات. يُسمح باستخدام القيم التالية:
    • وتشير السمة 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. يجب ضبط القيمة على الوقت الحالي أو على وقت ما في المستقبل. لا يمكن أن تكون في الماضي. (تحوّل واجهة برمجة التطبيقات جميع التواريخ إلى التوقيت العالمي المتفق عليه لضمان معالجة متّسقة عبر المناطق الزمنية). بالنسبة إلى عملاء الخطة المميّزة في "منصة خرائط Google"، إذا ضمّنت departureTime في الطلب، تعرض واجهة برمجة التطبيقات أفضل مسار وفقًا لظروف حركة المرور المتوقّعة في ذلك الوقت، وستضمِّن الوقت المتوقّع في حركة المرور (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 استخدام النظام الإمبراطوري (الإنجليزية). يتم عرض المسافات باستخدام الأميال.

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

انحياز المنطقة للاتّجاهات

تعرض خدمة اتجاهات واجهة برمجة التطبيقات لخرائط Google نتائج العناوين المتأثرة بالنطاق (المنطقة أو البلد) الذي حمَّلت منه برنامج بدء تشغيل JavaScript. (بما أنّ معظم المستخدمين يحمّلون https://maps.googleapis.com/ يؤدي ذلك إلى ضبط نطاق ضمني على الولايات المتحدة). وفي حال تحميل مسار التشغيل من نطاق متوافق آخر، ستظهر لك نتائج تتأثر بهذا النطاق. على سبيل المثال، قد تعرض عمليات البحث عن "سان فرانسيسكو" نتائج مختلفة من التطبيقات التي تُحمِّل https://maps.googleapis.com/ (الولايات المتحدة) مقارنةً بنتائج بحث واحدة يتم تحميلها في http://maps.google.es/ (إسبانيا).

يمكنك أيضًا ضبط خدمة "الاتجاهات" لعرض النتائج المتحيزة لمنطقة معيّنة باستخدام المعلَمة region. ويتم استخدام هذه المَعلمة كرمز منطقة، يتم تحديده كعلامة فرعية لمنطقة Unicode (غير رقمية) مكوَّنة من حرفَين. في معظم الحالات، يتم ربط هذه العلامات مباشرةً بقيم من حرفَين ضمن نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD)، مثل uk في co.uk على سبيل المثال. في بعض الحالات، تتوافق العلامة region أيضًا مع رموز ISO-3166-1 التي تختلف أحيانًا عن قيم ccTLD (مثلاً "GB" لـ "بريطانيا العظمى").

عند استخدام مَعلمة region:

  • يُرجى تحديد بلد واحد أو منطقة واحدة فقط. ويتم تجاهل قيم متعددة، ويمكن أن يؤدي ذلك إلى تعذّر تنفيذ الطلب.
  • استخدِم فقط علامات فرعية للمناطق من حرفَين (تنسيق Unicode CLDR). وستؤدي جميع الإدخالات الأخرى إلى حدوث أخطاء.

لا يتوفر انحياز المنطقة إلا للبلدان والمناطق التي تدعم الاتجاهات. يمكنك الرجوع إلى مقالة تفاصيل تغطية "منصة خرائط Google" للاطّلاع على التغطية الدولية لـ Directions 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 إلى تعذّرت معالجة طلب الاتجاهات بسبب خطأ في الخادم. قد ينجح الطلب إذا أعدت المحاولة.

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

عرض نتيجة الاتجاهات

يحتوي DirectionsResult على نتيجة طلب البحث عن الاتجاهات، ويمكنك إما معالجة هذه النتائج بنفسك أو نقلها إلى عنصر DirectionsRenderer يمكنه تلقائيًا معالجة عرض النتيجة على الخريطة.

لعرض DirectionsResult باستخدام DirectionsRenderer، يجب تنفيذ ما يلي:

  1. أنشِئ عنصر DirectionsRenderer.
  2. اطلب الرمز setMap() على العارض لربطه بالخريطة التي تم تمريرها.
  3. استدعِ الرمز setDirections() على جهاز العرض واضبطه DirectionsResult كما هو موضّح أعلاه. بما أنّ العارض هو MVCObject، سيرصد تلقائيًا أي تغييرات في سماته ويعدّل الخريطة عند تغيير الاتجاهات المرتبطة بها.

يحتسب المثال التالي الاتجاهات بين موقعَين جغرافيَين على الطريق 66، حيث يتم ضبط نقطة الانطلاق والوجهة حسب قيمتَي "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> لعرض هذه المعلومات. ويضمن ذلك أيضًا عرض معلومات حقوق الطبع والنشر المناسبة، وأي تحذيرات قد تكون مرتبطة بالنتيجة.

سيتم تقديم توجيهات نصية باستخدام إعدادات اللغة المفضّلة في المتصفّح أو اللغة المحدّدة عند تحميل JavaScript لواجهة برمجة التطبيقات باستخدام المعلَمة 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 متوقّفة نهائيًا في المسارات البديلة. الإصدار 3.27 هو الإصدار الأخير من واجهة برمجة التطبيقات الذي يضيف المزيد من خلال نقاط الطريق في المسارات البديلة. بالنسبة إلى الإصدار 3.28 والإصدارات الأحدث من واجهة برمجة التطبيقات، يمكنك مواصلة تنفيذ الاتجاهات القابلة للسحب باستخدام خدمة "الاتجاهات"، وذلك من خلال إيقاف سحب المسارات البديلة. يجب أن يكون المسار الرئيسي فقط قابلاً للسحب. ويمكن للمستخدمين سحب المسار الرئيسي إلى أن يتطابق مع مسار بديل.

نقاط الطرق المُرمَّزة جغرافيًا للاتّجاهات

يحتوي DirectionsGeocodedWaypoint على تفاصيل حول الترميز الجغرافي للمصدر والوجهة ونقاط الطريق.

DirectionsGeocodedWaypoint هو عنصر حرفي يتضمّن الحقول التالية:

  • تشير السمة geocoder_status إلى رمز الحالة الناتج عن عملية الترميز الجغرافي. قد يحتوي هذا الحقل على القيم التالية.
    • يشير "OK" إلى عدم حدوث أي أخطاء، حيث تم تحليل العنوان بنجاح وتم عرض رمز جغرافي واحد على الأقل.
    • يشير "ZERO_RESULTS" إلى أن الرمز الجغرافي كان ناجحًا ولكنه لم يعرض أي نتائج. قد يحدث هذا إذا تم تمرير رمز الموقع الجغرافي إلى address غير موجود.
  • يشير partial_match إلى أن أداة الترميز الجغرافي لم تعرض تطابقًا تامًا للطلب الأصلي، على الرغم من تمكّنها من مطابقة جزء من العنوان المطلوب. ننصحك بفحص الطلب الأصلي بحثًا عن أخطاء إملائية و/أو إذا كان العنوان غير مكتمل.

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

  • place_id هو معرّف فريد للمكان، ويمكن استخدامه مع واجهات Google APIs الأخرى. على سبيل المثال، يمكنك استخدام 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 مع ثلاث سمات:
  • يتضمّن departure_time وقت المغادرة المقدَّر لهذه المرحلة، والذي تم تحديده كعنصر Time. لا يتوفّر departure_time إلا لاتجاهات النقل العام.
  • تحتوي السمة start_location على LatLng لمصدر هذه الساق. بما أنّ خدمة ويب الاتجاهات تحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب خيار من وسائل النقل (عادةً ما تكون طريقًا) عند نقطتَي البداية والنهاية، قد يكون start_location مختلفًا عن نقطة الانطلاق المحدّدة لهذه المحطة إذا كانت الطريق مثلاً ليست بالقرب من نقطة الانطلاق.
  • تحتوي end_location على LatLng لوجهة هذه المحطة. بما أنّ DirectionsService تحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب خيار لوسائل النقل (عادةً ما تكون طريقًا) عند نقطتَي البداية والنهاية، قد تكون السمة end_location مختلفة عن الوجهة المقدَّمة في هذه المرحلة، إذا كانت الطريق مثلاً ليست بالقرب من الوجهة.
  • يتضمّن start_address العنوان الذي يمكن لشخص عادي قراءته (عادةً ما يكون عنوان الشارع) لبداية هذه المرحلة.

    يتم قراءة هذا المحتوى كما هو، لذا لا تحلّل العنوان المنسَّق بشكل آلي.
  • يتضمّن end_address العنوان الذي يمكن لشخص عادي قراءته (عادةً عنوان الشارع) لنهاية هذه المحطة.

    يتم قراءة هذا المحتوى كما هو، لذا لا تحلّل العنوان المنسَّق بشكل آلي.

خطوات الحصول على الاتجاهات

السمة DirectionsStep هي الوحدة الذرّية في مسار الاتجاه، وتحتوي على خطوة واحدة تصف تعليمات محدّدة وواحدة حول الرحلة. مثال: "الاتجاه يسارًا عند الغرب الشارع الرابع" لا تصف الخطوة التعليمات فقط، بل تحتوي أيضًا على معلومات حول المسافة والمدة تتعلّق بكيفية ارتباط هذه الخطوة بالخطوة التالية. على سبيل المثال، قد تتضمّن الخطوة التي يتم الإشارة إليها باسم "الدمج في I-80 West" مدة "37 ميلاً" و "40 دقيقة"، ما يشير إلى أنّ الخطوة التالية هي 37 ميلاً/40 دقيقة من هذه الخطوة.

عند استخدام خدمة "الاتجاهات" للبحث عن اتجاهات النقل العام، ستتضمّن مصفوفة الخطوات معلومات إضافية خاصة بالنقل العام على شكل عنصر transit. إذا كانت الاتجاهات تشمل وسائل نقل متعددة، سيتم تقديم اتجاهات مفصّلة للمشي أو القيادة في مصفوفة steps[]. على سبيل المثال، ستتضمن خطوة المشي الاتجاهات من موقعي البداية والنهاية: "المشي إلى شارع السلام". وستتضمّن هذه الخطوة اتجاهات المشي التفصيلية لهذا المسار في مجموعة steps[]، مثل: "الاتجاه إلى الشمال الغربي" و"الانعطاف لليسار" و"الاتجاه يسارًا إلى جادة Innes Ave".

DirectionsStep هو عنصر حرفي يتضمّن الحقول التالية:

  • يحتوي instructions على تعليمات لهذه الخطوة ضمن سلسلة نصية.
  • يتضمّن distance المسافة التي تغطيها هذه الخطوة حتى الخطوة التالية، ككائن Distance. (اطّلِع على الوصف في DirectionsLeg أعلاه.) وقد تكون هذه المسافة غير معروفة إذا كانت المسافة غير معروفة.
  • يتضمّن duration تقديرًا للوقت المطلوب لتنفيذ الخطوة حتى الخطوة التالية، على أنّه عنصر Duration. (اطّلِع على الوصف الوارد في DirectionsLeg أعلاه.) قد يكون هذا الحقل غير محدّد إذا كانت المدة غير معروفة.
  • يحتوي start_location على الرمز LatLng المرمز جغرافيًا لنقطة بداية هذه الخطوة.
  • يتضمّن end_location السمة LatLng لنقطة النهاية لهذه الخطوة.
  • يحتوي polyline على عنصر points واحد يتضمّن تمثيلاً لخطوط متعددة مرمّزة للخطوة. وهذا الخط المتعدد هو مسار تقريبي (متجانس) للخطوة.
  • steps[] هو عنصر DirectionsStep حرفي يتضمّن اتجاهات مفصّلة للمشي أو خطوات القيادة في اتجاهات النقل العام. لا تتوفّر الخطوات الفرعية إلا لاتجاهات النقل العام.
  • يتضمّن travel_mode عنصر TravelMode المستخدَم في هذه الخطوة. وقد تشمل اتجاهات النقل العام مجموعة من اتجاهات المشي واتجاهات النقل العام.
  • تحتوي السمة path على مصفوفة من LatLngs تصف مسار هذه الخطوة.
  • تحتوي السمة transit على معلومات خاصة بالنقل العام، مثل أوقات الوصول والمغادرة، واسم خط النقل العام.

معلومات خاصة بالنقل العام

تعرض اتجاهات النقل العام معلومات إضافية لا صلة لها بوسائل النقل الأخرى. يتم عرض هذه السمات الإضافية من خلال العنصر TransitDetails، ويتم عرضها كسمة DirectionsStep. من الكائن TransitDetails، يمكنك الوصول إلى معلومات إضافية للكائنات TransitStop وTransitLine وTransitAgency وVehicleType كما هو موضّح أدناه.

تفاصيل النقل العام

يعرض الكائن TransitDetails السمات التالية:

  • يحتوي arrival_stop على عنصر TransitStop يمثّل محطة الوصول/محطة الوصول مع السمات التالية:
    • name اسم محطة/محطة النقل العام مثال: "ساحة الاتحاد".
    • location موقع محطة/محطة النقل العام، ويتم تمثيلها على أنّها LatLng.
  • يحتوي departure_stop على عنصر TransitStop يمثّل محطة المغادرة.
  • يحتوي السمة arrival_time على وقت الوصول المحدد كعنصر Time مع ثلاث سمات:
  • يحتوي departure_time على وقت المغادرة المحدد ككائن Time.
  • تحدّد السمة headsign الاتجاه الذي يجب السير فيه على هذا الخط، حيث يتم وضع علامة عليه على المركبة أو عند محطة المغادرة. ستكون هذه غالبًا محطة النهاية.
  • تحدّد هذه السمة headway، عند توفّرها، عدد الثواني المتوقّعة بين أوقات المغادرة من المحطة نفسها في الوقت الحالي. على سبيل المثال، إذا كانت قيمة headway هي 600، يمكنك الانتظار لمدة عشر دقائق إذا فاتتك الحافلة.
  • يحتوي line على العنصر الحرفي TransitLine يحتوي على معلومات حول خط النقل العام المستخدَم في هذه الخطوة. توفّر السمة TransitLine اسم السطر وعامل تشغيله، إلى جانب سمات أخرى موضّحة في المستندات المرجعية TransitLine.
  • يتضمّن num_stops عدد محطات التوقف في هذه الخطوة. تشمل هذه الفئة محطة الوصول، وليس محطة المغادرة. على سبيل المثال، إذا كانت اتجاهاتك تتضمّن المغادرة من المحطة "أ" والمرور بالمحطتَين "ب" و"ج" والوصول إلى المحطة "د"، سيعرض num_stops الرقم 3.

خط رحلة

يعرض الكائن TransitLine السمات التالية:

  • يحتوي name على الاسم الكامل لخط النقل العام هذا. على سبيل المثال: "شارع 7 إكسبرس" أو "شارع عباس العقاد"
  • يحتوي short_name على الاسم المختصر لخط النقل العام هذا. وسيكون في العادة رقم سطر مثل "2" أو "M14".
  • agencies هي مصفوفة تحتوي على عنصر TransitAgency واحد. يقدّم الكائن TransitAgency معلومات عن عامل تشغيل هذا السطر، بما في ذلك السمات التالية:
    • يحتوي name على اسم مؤسسة النقل العام.
    • يحتوي phone على رقم هاتف مؤسسة النقل العام.
    • يحتوي url على عنوان URL الخاص بمؤسسة النقل العام.

    ملاحظة: إذا كنت تعرض اتجاهات النقل العام يدويًا بدلاً من استخدام العنصر DirectionsRenderer، يجب عرض أسماء وعناوين URL لمؤسسات النقل العام التي تقدّم نتائج الرحلة.

  • تحتوي url على عنوان URL لخط النقل العام هذا كما تقدّمه مؤسسة النقل العام.
  • يحتوي icon على عنوان URL للرمز المرتبط بهذا السطر. ستستخدم معظم المدن رموزًا عامة تختلف حسب نوع المركبة. تتضمّن بعض خطوط النقل العام، مثل نظام مترو الأنفاق في نيويورك، رموزًا خاصة بهذا الخط.
  • تحتوي السمة color على اللون الذي يشيع استخدامه في اللافتات الخاصة بعملية النقل هذه. سيتم تحديد اللون كسلسلة سداسية عشرية مثل: #FF0033.
  • يحتوي text_color على لون النص الذي يشيع استخدامه في لافتات هذا الخط. سيتم تحديد اللون كسلسلة سداسية عشرية.
  • يحتوي vehicle على عنصر Vehicle الذي يتضمّن السمات التالية:
    • يحتوي name على اسم المركبة على هذا الخط. مثال: "مترو الأنفاق".
    • يتضمّن type نوع المركبة المستخدمة على هذا الخط. يُرجى الاطّلاع على مستندات نوع المركبة للحصول على قائمة كاملة بالقيم المسموح بها.
    • تحتوي icon على عنوان URL للرمز المرتبط عادةً بهذا النوع من المركبات.
    • تحتوي السمة local_icon على عنوان URL للرمز المرتبط بنوع المركبة هذا، استنادًا إلى لافتات النقل المحلية.

نوع المركبة

يعرض الكائن VehicleType السمات التالية:

القيمة التعريف
VehicleType.RAIL السكك الحديدية
VehicleType.METRO_RAIL النقل العام بالسكك الحديدية الخفيفة:
VehicleType.SUBWAY قطار خفيف تحت الأرض.
VehicleType.TRAM قطار خفيف فوق الأرض.
VehicleType.MONORAIL قطار بخط حديدي واحد
VehicleType.HEAVY_RAIL السكة الحديدية الثقيلة:
VehicleType.COMMUTER_TRAIN قطار تنقّل:
VehicleType.HIGH_SPEED_TRAIN قطار عالي السرعة
VehicleType.BUS حافلة
VehicleType.INTERCITY_BUS حافلة بين المدن.
VehicleType.TROLLEYBUS حافلة كهربائية.
VehicleType.SHARE_TAXI سيارة الأجرة المشتركة هي نوع من الحافلات تتيح إمكانية النزول واصطحاب الركاب في أي مكان على مساره.
VehicleType.FERRY العبّارة
VehicleType.CABLE_CAR يشير ذلك المصطلح إلى مركبة تعمل باستخدام كابل، وعادةً ما تكون على الأرض. وقد تكون عربات الكابلات الجوية من النوع VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT تلفريك جوي.
VehicleType.FUNICULAR مركبة يتم سحبها لمستوى انحدار شديد بواسطة كابل. يتكوّن القطار الجبلي المائل عادةً من سيارتَين، وتؤخذ كل سيارة كوزن موازن للسيارة الأخرى.
VehicleType.OTHER ستعرض جميع المركبات الأخرى هذا النوع.

فحص نتائج الاتجاهات

يمكن فحص مكوّنات DirectionsResults، وهي DirectionsRoute وDirectionsLeg وDirectionsStep وTransitDetails، واستخدامها عند تحليل أيّ استجابة للاتجاهات.

ملاحظة مهمة: إذا كنت تعرض اتجاهات النقل العام يدويًا بدلاً من استخدام العنصر DirectionsRenderer، عليك عرض أسماء وعناوين URL الخاصة بمؤسسات النقل العام التي تقدّم خدمة نتائج الرحلات.

يوضِّح المثال التالي اتجاهات المشي للوصول إلى معالم سياحية معيّنة في مدينة نيويورك. نفحص DirectionsStep للمسار لإضافة علامات لكل خطوة، ونرفِق معلومات بـ InfoWindow تحتوي على نص تعليمي لهذه الخطوة.

ملاحظة: بما أنّنا نحتسب اتجاهات المشي، نعرض أيضًا أي تحذيرات للمستخدم في لوحة <div> منفصلة.

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);
  });
}

في نص HTML:

<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>

الاطّلاع على مثال

استخدام نقاط الطرق في المسارات

كما هو موضّح في DirectionsRequest، يمكنك أيضًا تحديد نقاط الطرق (من النوع DirectionsWaypoint) عند حساب المسارات باستخدام خدمة "الاتجاهات" للمشي أو ركوب الدراجات أو اتجاهات القيادة. لا تتوفّر نقاط الطرق لاتجاهات النقل العام. تتيح لك نقاط الطرق حساب المسارات من خلال مواقع إضافية، وفي هذه الحالة يمر المسار المعروض عبر نقاط الطريق المحددة.

يتكوّن waypoint من الحقول التالية:

  • location (مطلوبة) تحدد عنوان النقطة الوسيطة.
  • تشير السمة stopover (اختيارية) إلى ما إذا كانت نقطة الطريق هذه محطة فعلية على المسار (true) أو بدلاً من ذلك تفضيلاً للتوجيه عبر الموقع المُشار إليه (false). وتكون محطات التوقف true بشكل تلقائي.

تحسب خدمة الاتجاهات تلقائيًا مسارًا عبر نقاط الطريق المتوفّرة بترتيبها المحدّد. اختياريًا، يمكنك تمرير optimizeWaypoints: true داخل DirectionsRequest للسماح لخدمة "الاتجاهات" بتحسين المسار المقدّم من خلال إعادة ترتيب نقاط الطريق بترتيب أكثر فعالية. (يهدف هذا التحسين إلى حلّ مشكلة مندوب المبيعات المتنقلين). إنّ مدة الرحلة هي العامل الأساسي الذي يتم تحسينه، ولكن قد يتم أخذ عوامل أخرى في الاعتبار عند تحديد المسار الأكثر كفاءة، مثل المسافة وعدد الدورات وغير ذلك. يجب أن تكون جميع نقاط الطرق محطات توقف لخدمة "الاتجاهات" لتحسين مسارها.

إذا طلبت من خدمة الاتجاهات تحسين ترتيب نقاط الطريق، سيتم عرض ترتيبها في الحقل waypoint_order ضمن الكائن DirectionsResult.

يحتسب المثال التالي المسارات عبر البلدان في الولايات المتحدة باستخدام مجموعة متنوعة من نقاط البداية ونقاط النهاية ونقاط الطرق. (لتحديد نقاط طريق متعددة، اضغط على Ctrl مع النقر عند اختيار عناصر ضمن القائمة). يُرجى العِلم أنّنا نفحص routes.start_address وroutes.end_address لنوفّر لنا النص الخاص بنقطة البداية والنهاية لكل مسار.

TypeScript

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;

JavaScript

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;

الحدود والقيود المفروضة على نقاط الطرق

تنطبق حدود الاستخدام وحدود الاستخدام التالية:

  • الحد الأقصى لعدد نقاط الطريق المسموح بها عند استخدام خدمة الاتجاهات في واجهة برمجة تطبيقات JavaScript للخرائط هو 25 نقطة، بالإضافة إلى نقطة الانطلاق والوجهة. يتم تطبيق الحدود نفسها على خدمة الويب Directions API.
  • بالنسبة إلى خدمة الويب Directions API، يُسمَح للعملاء بإضافة 25 نقطة طريق، بالإضافة إلى نقطة الانطلاق والوجهة.
  • يُسمح لعملاء الخطة المميّزة في "منصة خرائط Google" بالوصول إلى 25 نقطة مسار بالإضافة إلى نقطة الانطلاق والوجهة.
  • نقاط الطرق غير متاحة لاتجاهات النقل العام.

الاتجاهات القابلة للسحب

ويمكن للمستخدمين تعديل اتجاهات ركوب الدراجات أو المشي أو القيادة المعروضة باستخدام DirectionsRenderer ديناميكيًا إذا كانت قابلة للسحب، ما يسمح للمستخدم باختيار المسارات وتغييرها بالنقر على المسارات الناتجة على الخريطة وسحبها. ويمكنك توضيح ما إذا كانت شاشة العرض تسمح بسحب الاتجاهات من خلال ضبط السمة draggable على true. لا يمكن جعل اتجاهات النقل العام قابلة للسحب.

عندما تكون الاتجاهات قابلة للسحب، يمكن للمستخدم اختيار أي نقطة على مسار (أو نقطة وسيطة) النتيجة المعروضة ونقل العنصر المُشار إليه إلى موقع جديد. سيتم تعديل DirectionsRenderer ديناميكيًا لعرض المسار المعدَّل. وعند الإصدار، ستتم إضافة نقطة طريق انتقالية إلى الخريطة (يُشار إليها بعلامة بيضاء صغيرة). سيؤدي اختيار وتحريك جزء من المسار إلى تغيير جزء المسار، بينما سيؤدي اختيار علامة نقطة الطريق وتحريكها (بما في ذلك نقطتا البداية والنهاية) إلى تغيير ساقي المسار الذي يمر من نقطة الطريق تلك.

بما أنّه يتم تعديل الاتجاهات القابلة للسحب وعرضها من جهة العميل، ننصحك بمراقبة حدث directions_changed والتعامل معه على DirectionsRenderer ليتم إرسال إشعار إليك عندما يعدِّل المستخدم الاتجاهات المعروضة.

يُظهر الرمز التالي رحلة من بيرث على الساحل الغربي لأستراليا إلى سيدني على الساحل الشرقي. يراقب الرمز حدث directions_changed لتعديل المسافة الإجمالية لجميع مراحل الرحلة.

TypeScript

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;

JavaScript

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;
الاطّلاع على مثال

تجربة العينة