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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

نظرة عامة

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

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

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

البدء

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

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

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

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

السعر

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

السياسات

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

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

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

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

عرض الاتجاهات

إنّ بدء طلب الاتجاهات إلى 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>

عرض مثال

كائن Directionsالنتيجة

عند إرسال طلب للحصول على الاتجاهات إلى 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 APIs الأخرى. على سبيل المثال، يمكنك استخدام place_id مع مكتبة واجهة برمجة تطبيقات أماكن Google للحصول على تفاصيل نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين والمزيد. اطّلِع على نظرة عامة على رقم تعريف المكان.
  • السمة types[] هي مصفوفة تشير إلى type للنتيجة المعروضة. تحتوي هذه المصفوفة على مجموعة صفرية أو أكثر من العلامات تحدّد نوع الميزة المعروضة في النتيجة. على سبيل المثال، يشير الموقع الجغرافي لـ "شيكاغو" إلى "المنطقة المحلية" التي تشير إلى أن "شيكاغو" مدينة، كما تعرض أيضًا "السياسة" التي تشير إلى أنها كيان سياسي.

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

ملاحظة: تمت إعادة تسمية العنصر DirectionsTrip القديم DirectionsRoute. يُرجى العِلم أنّ المسار يشير الآن إلى مسار الرحلة بالكامل إلى نهايته، وليس فقط جزء من رحلة أحد الوالدَين.

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

السمة DirectionsRoute هي عبارة عن عنصر حرفي في الحقول التالية:

  • يتضمّن legs[] مصفوفة من DirectionsLeg، يحتوي كل منها على معلومات عن جزء من المسار، من موقعَين ضمن المسار المحدّد. ستظهر ساق منفصلة لكل نقطة طريق أو وجهة محدّدة. (المسار الذي لا يحتوي على نقاط مسار سيتضمّن DirectionsLeg واحد بالضبط). وتتكوّن كل مرحلة من سلسلة من DirectionStep.
  • يحتوي waypoint_order على مصفوفة تشير إلى ترتيب أي نقاط مسار في المسار المَحسوب. قد تحتوي هذه المصفوفة على ترتيب تم تغييره إذا تم تمرير DirectionsRequest optimizeWaypoints: true.
  • يحتوي overview_path على مصفوفة من LatLngs التي تمثل مسارًا تقريبيًا (ناعمًا) للاتجاهات الناتجة.
  • يحتوي 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 يحمل ثلاث خصائص:
    • value الوقت المحدّد كعنصر Date في JavaScript
    • text الوقت المحدّد كسلسلة يتم عرض الوقت بتوقيت المنطقة الزمنية لمحطّة النقل العام.
    • تحتوي time_zone على المنطقة الزمنية لهذه المحطة. وهذه القيمة هي اسم المنطقة الزمنية كما هو محدّد في قاعدة بيانات المناطق الزمنية (IANA)، مثل "America/New_York".
  • تتضمّن السمة departure_time وقت المغادرة المقدَّر لهذه المحطة، والمحدَّدة كعنصر Time. لا يتوفّر departure_time سوى لاتجاهات النقل العام.
  • تحتوي السمة start_location على LatLng من أصل هذه المحطة. بما أنّ خدمة الويب للحصول على الاتجاهات تحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب خيار للنقل (عادةً ما يكون طريقًا) في نقاط البداية والنهاية، قد تختلف start_location عن نقطة الانطلاق هذه للساقين، مثلاً، إذا لم يكن هناك طريق بالقرب من نقطة الانطلاق.
  • تحتوي السمة end_location على LatLng لوجهة هذه المحطة. بما أنّ DirectionsService تحسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب خيار للنقل (عادةً ما يكون طريقًا) في نقاط البداية والنهاية، قد تكون end_location مختلفة عن الوجهة المقدَّمة لهذه السيارة إذا لم تكن طريق بالقرب من الوجهة مثلاً.
  • يحتوي start_address على العنوان الذي يمكن أن يقرأه المستخدم (عادةً عنوان الشارع) في بداية هذه المرحلة.

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

    المقصود من هذا المحتوى أن تتم قراءته كما هو، ولا تحلّل العنوان المنسَّق آليًا.

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

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

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

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

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

معلومات النقل العام

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

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

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

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

خط رحلة

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

  • يحتوي name على الاسم الكامل لخط النقل العام هذا. على سبيل المثال "7 جادة سريعة" أو "14 سانت كروستاون".
  • تتضمّن السمة 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 نقطة، بالإضافة إلى نقطة الانطلاق والوجهة. هذه الحدود هي نفسها في خدمة Web API للتوجيهات.
  • بالنسبة إلى خدمة الويب Directions API، يُسمح للعملاء بـ 25 نقطة مسار، بالإضافة إلى نقطة الانطلاق والوجهة.
  • يُسمح لعملاء خطة Premium في "خرائط 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;
عرض مثال

جرّب عيّنة