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

نظرة عامة

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

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

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

الخطوات الأولى

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

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

  1. انتقِل إلى Google Cloud Console.
  2. انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة التطبيقات JavaScript API في "خرائط Google"، ثم انقر على فتح.
  3. من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Directions API (الإصدار القديم).
  4. إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك قد أكملت الخطوات اللازمة. إذا لم تكن واجهة برمجة التطبيقات مُدرَجة، يمكنك تفعيلها على الرابط: https://console.cloud.google.com/apis/library/directions-backend.googleapis.com

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

التسعير

للاطّلاع على معلومات عن أسعار خدمة "الاتجاهات" المستندة إلى JavaScript وسياسات الاستخدام، يُرجى الاطّلاع على الاستخدام والفوترة لواجهة برمجة التطبيقات Directions API (الإصدار القديم).

السياسات

يجب أن يكون استخدام خدمة "الاتجاهات" متوافقًا مع السياسات الموضّحة لواجهة برمجة التطبيقات Directions API (الإصدار القديم).

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

إنّ الوصول إلى خدمة "الاتجاهات" غير متزامن، لأنّ واجهة برمجة التطبيقات في "خرائط Google" تحتاج إلى إجراء طلب إلى خادم خارجي. لهذا السبب، عليك تمرير طريقة callback لتنفيذها عند اكتمال الطلب. من المفترض أن تعالج طريقة callback هذه النتائج. يُرجى العلم أنّه قد تعرض خدمة "الاتجاهات" أكثر من خط سير محتمل واحد كصفيف من 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 (على سبيل المثال، "القاهرة، مصر")، أو على أنّها قيمة LatLng ، أو على أنّها عنصر مكان. إذا كنت تستخدم عنصر مكان، يمكنك تحديد معرّف مكان أو سلسلة طلب بحث أو موقع جغرافي LatLng. يمكنك استرداد أرقام تعريف الأماكن من خدمات "ترميز المواقع الجغرافية" و "بحث الأماكن" و"الإكمال التلقائي للأماكن" في Maps JavaScript API. للحصول على مثال على استخدام أرقام تعريف الأماكن من ميزة "الإكمال التلقائي للأماكن"، يُرجى الاطّلاع على مقالة ميزة "الإكمال التلقائي للأماكن" وميزة "الاتجاهات".
  • ‫destination (مطلوبة) لتحديد الموقع الجغرافي النهائي الذي يتم احتساب الاتجاهات إليه الخيارات هي نفسها الخيارات المتاحة في حقل origin الموضّح أعلاه.
  • ‫travelMode (مطلوبة) تحدِّد نوع وسيلة النقل التي سيتم استخدامها عند احتساب الاتجاهات. يتم تحديد القيم الصالحة في وسائل النقل أدناه.
  • transitOptions (اختياري) يحدِّد القيم التي تنطبق فقط على الطلبات التي يكون فيهاtravelMode TRANSIT. يتم وصف القيم الصالحة في خيارات النقل أدناه.
  • drivingOptions (اختياري) يحدِّد القيم التي تنطبق فقط على الطلبات التي يكون فيهاtravelMode DRIVING. يتم وصف القيم الصالحة في خيارات القيادة أدناه.

  • ‫unitSystem (اختياري) يحدِّد نظام الوحدات الذي يجب استخدامه عند عرض النتائج. يتم تحديد القيم الصالحة في أنظمة الوحدات أدناه.

  • ‫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'
  }
}

أنظمة الوحدات

يتم تلقائيًا احتساب الاتجاهات وعرضها باستخدام نظام الوحدات في البلد أو المنطقة الأصلية. (ملاحظة: يتم دائمًا استخدام الوحدات المترية بدلاً من الوحدات الإمبراطورية في المواقع الجغرافية التي يتم التعبير عنها باستخدام إحداثيات خط العرض/خط الطول بدلاً من العناوين). على سبيل المثال، سيعرض المسار من "شيكاغو، إلينوي" إلى "تورنتو، أونتاريو" النتائج بالأميال، بينما سيعرض المسار العكسي النتائج بالكيلومترات. يمكنك إلغاء نظام الوحدات هذا من خلال ضبط نظام آخر صراحةً في طلب باستخدام إحدى قيم UnitSystem التالية:

  • UnitSystem.METRIC تحدد استخدام النظام المتري. يتم عرض المسافات باستخدام الكيلومترات.
  • يحدِّد UnitSystem.IMPERIAL استخدام النظام الإمبراطوري (الإنجليزي). يتم عرض المسافات باستخدام الأميال.

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

التركيز على منطقة معيّنة في عرض الاتجاهات

تعرض خدمة "الاتجاهات" في Google Maps API نتائج العناوين التي تتأثر بالنطاق (المنطقة أو البلد) الذي حمّلت منه ملف JavaScript التمهيد. (بما أنّ معظم المستخدمين يزوّدون https://maps.googleapis.com/ ببيانات، يتم ضبط نطاق ضمني على الولايات المتحدة). في حال تحميل ملف التمهيد من نطاق متوافق مختلف، ستحصل على نتائج متأثرة بهذا النطاق. على سبيل المثال، قد تؤدي عمليات البحث عن "الإسكندرية" إلى عرض نتائج مختلفة في التطبيقات التي يتم تحميلها https://maps.googleapis.com/ (الولايات المتحدة) عن التطبيقات التي يتم تحميلها http://maps.google.es/ (إسبانيا).

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

يحتوي العنصر 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 إلى أنّ أداة ترميز المواقع الجغرافية لم تُعرِض مطابقة تامّة للطلب الأصلي، إلا أنّها تمكّنت من مطابقة جزء من العنوان المطلوب. ننصحك بفحص الطلب الأصلي بحثًا عن أخطاء إملائية و/أو عنوان غير كامل.

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

  • place_id هو معرّف فريد للمكان، ويمكن استخدامه مع واجهات برمجة تطبيقات Google الأخرى. على سبيل المثال، يمكنك استخدام place_id مع مكتبة Google Places API للحصول على تفاصيل عن نشاط تجاري محلي، مثل رقم الهاتف، وساعات العمل، ومراجعات المستخدمين، وغير ذلك. اطّلِع على نظرة عامة على معرّف المكان.
  • types[] هو صفيف يشير إلى نوع النتيجة المعروضة. تحتوي هذه المصفوفة على مجموعة من علامات صفرية أو أكثر تحدِّد نوع العنصر الذي يتم عرضه في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي لمدينة "القاهرة" القيمة "locality" التي تشير إلى أنّ "القاهرة" هي مدينة، ويعرض أيضًا القيمة "political" التي تشير إلى أنّها كيان سياسي.

مسارات الاتجاهات

ملاحظة: تمت إعادة تسمية العنصر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 دائمًا على قيمة expressed بالمتر.

    قد تكون هذه الحقول غير محدّدة إذا كانت المسافة غير معروفة.

  • يشير duration إلى إجمالي مدة هذه المرحلة، كعنصر Duration من الشكل التالي:

    • يشير value إلى المدة بالثواني.
    • يحتوي text على تمثيل سلسلة للمدة.

    قد لا تكون هذه الحقول محدّدة إذا كانت المدة غير معروفة.

  • يشير duration_in_traffic إلى إجمالي مدة هذه المرحلة، مع الأخذ في الاعتبار ظروف حركة المرور الحالية. لا يتم عرض الرمز duration_in_traffic إلا إذا كانت كل الشروط التالية صحيحة:

    • لا يتضمّن الطلب نقاط التوقف. وهذا يعني أنّه لا يتضمّن نقاط الطريق التي يكون فيها stopover هو true.
    • الطلب مخصّص لاتجاهات القيادة تحديدًا، وتم ضبط mode على driving.
    • يتم تضمين departureTime كجزء من الحقل drivingOptions في الطلب.
    • تتوفّر معلومات عن أحوال حركة المرور للمسار المطلوب.

    يحتوي duration_in_traffic على الحقول التالية:

    • يشير value إلى المدة بالثواني.
    • يحتوي text على تمثيل سهل الفهم للمدة.
  • يحتوي الحقل arrival_time على الوقت المقدَّر للوصول لهذه المرحلة. لا يتم عرض هذه السمة إلا لاتجاهات النقل العام. يتم عرض النتيجة على أنّها عنصر Time يتضمّن ثلاث سمات:
    • value الوقت المحدّد بتنسيق كائن JavaScript Date
    • text الوقت المحدّد كسلسلة يتم عرض الوقت حسب المنطقة الزمنية لمحطة النقل العام.
    • يحتوي الحقل time_zone على المنطقة الزمنية لهذه المحطة. قيمة هي اسم المنطقة الزمنية كما هو محدّد في قاعدة بيانات مناطق IANA الزمنية، على سبيل المثال "أمريكا/نيويورك".
  • يحتوي departure_time على الوقت المقدَّر للمغادرة لهذه المرحلة، المحدَّد كعنصر Time. لا يتوفّر الرمز departure_time إلا لاتجاهات النقل العام.
  • يحتوي start_location على LatLng لنقطة انطلاق هذه المرحلة. بما أنّ خدمة الاتجاهات على الويب تحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب خيار للنقل (عادةً ما يكون طريقًا) عند نقطتَي البداية والنهاية، قد يختلف start_location عن نقطة المصدر المقدَّمة لهذه المرحلة إذا كانت مثلاً الطريق غير قريبة من نقطة المصدر.
  • يحتوي end_location على LatLng لوجهة هذه المرحلة. بما أنّ DirectionsService تحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب خيار للنقل (عادةً ما يكون طريقًا) عند نقطة البدء والنهاية، قد يختلف end_location عن الوجهة المقدَّمة لهذه المرحلة إذا لم تكن هناك طريق بالقرب من الوجهة، مثلاً.
  • يحتوي الحقل start_address على العنوان القابل للقراءة (عادةً عنوان شارع) لبداية هذه المرحلة.

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

    يُقصد قراءة هذا المحتوى كما هو. لا تُحلِّل العنوان بالتنسيق آليًا.

خطوات التوجيهات

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

عند استخدام خدمة "الاتجاهات" للبحث عن اتجاهات النقل العام، ستتضمّن صفيف الخطوات معلومات إضافية خاصة بالنقل العام في شكل عنصر transit. إذا كانت الاتجاهات تتضمّن طرق نقل متعددة، سيتم توفير اتجاهات تفصيلية لخطوات المشي أو القيادة في مصفوفة steps[]. على سبيل المثال، ستتضمّن خطوة المشي الاتجاهات من الموقع الجغرافي للبدء والانتهاء: "المشي إلى شارع Innes Ave & Fitch St". ستتضمّن هذه الخطوة اتجاهات مفصّلة للمشي في هذا المسار في صفيف steps[] ، مثل: "اتّجه شمال غربًا" و"استدر يسارًا إلى شارع Arelious Walker" و "استدر يسارًا إلى شارع 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 يتضمّن ثلاث سمات:
    • value الوقت المحدّد بتنسيق كائن JavaScript Date
    • text الوقت المحدّد كسلسلة يتم عرض الوقت حسب المنطقة الزمنية لمحطة النقل العام.
    • يحتوي الحقل time_zone على المنطقة الزمنية لهذه المحطة. قيمة هي اسم المنطقة الزمنية كما هو محدّد في قاعدة بيانات مناطق IANA الزمنية، على سبيل المثال "أمريكا/نيويورك".
  • يحتوي departure_time على وقت المغادرة، المحدّد كعنصر Time.
  • headsign يحدّد اتجاه التنقّل على هذا الخط، كما هو موضّح على المركبة أو في محطة المغادرة. وغالبًا ما تكون هذه المحطة هي المحطة النهائية.
  • headway عند توفّرها، تحدّد هذه السمة عدد الثواني المتوقع بين الرحلات من المحطة نفسها في هذا الوقت. على سبيل المثال، عند ضبط قيمة headway على 600، من المتوقّع الانتظار لمدة عشرة دقائق في حال تأخّرك عن الحافلة.
  • يحتوي line على عنصر TransitLine حرفي يحتوي على معلومات عن خط النقل العام المستخدَم في هذه الخطوة. يوفّر العنصر TransitLine اسم السطر ومشغّله، بالإضافة إلى السمات الأخرى الموضّحة في مستند مرجعي TransitLine.
  • يحتوي الحقل num_stops على عدد محطات التوقف في هذه الخطوة. ويشمل ذلك محطة الوصول، ولكن ليس محطة المغادرة. على سبيل المثال، إذا كانت الاتجاهات تتضمن المغادرة من المحطة "أ" والمرور بالمحطتَين "ب" و "ج" والوصول إلى المحطة "د"، سيعرض num_stops القيمة 3.

خط النقل العام

يعرِض عنصر TransitLine السمات التالية:

  • يحتوي الحقل name على الاسم الكامل لخط النقل العام هذا، على سبيل المثال: "7 Avenue Express" أو "14th St Crosstown"
  • يحتوي الحقل 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-Click عند اختيار العناصر ضمن القائمة). يُرجى العِلم أنّنا نتحقّق من 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;
index.ts

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;
index.js

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

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

  • الحد الأقصى المسموح به لعدد نقاط الالتفاف عند استخدام خدمة "الاتجاهات" في واجهة برمجة التطبيقات Maps JavaScript API هو 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;
index.ts

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;
index.js
عرض مثال

تجربة عيّنة