تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

ملاحظة: المكتبات من جهة الخادم

نظرة عامة

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

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

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

البدء

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

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

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

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

التسعير

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

السياسات

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

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

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

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

ملاحظة: تم إيقاف الحقل durationInTraffic. وكانت هذه الطريقة هي المُقترَحة سابقًا لعملاء خطة "منصة خرائط Google" المميّزة لتحديد ما إذا كانت النتيجة يجب أن تتضمّن مدة تراعي شروط الزيارات الحالية. عليك الآن استخدام الحقل drivingOptions بدلاً من ذلك.

في ما يلي نموذج 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 التي يتم عرضها يجب أن تكون أقصر من وقت السفر الفعلي في معظم الأيام، ولكن قد تكون الأيام التي تكون فيها أحوال حركة المرور جيّدة أسرع من هذه القيمة.

ملاحظة: لضمان استخدام طلبك لمعلومات حركة المرور المباشرة، اضبط السمة departureTime الآن. وتتم فوترة الطلبات التي تستخدم معلومات حركة المرور بمعدل أعلى. اطّلِع على مزيد من المعلومات عن كيفية تحصيل الرسوم مقابل منتجات "منصة خرائط Google".

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

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

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

لا يتوفّر انحياز المنطقة إلا للبلدان والمناطق التي تتيح الاتجاهات. راجِع تفاصيل تغطية "منصة خرائط Google" للاطّلاع على التغطية الدولية لواجهة برمجة التطبيقات Directions.

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

إنّ بدء طلب اتجاهات إلى 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، يجب تنفيذ ما يلي:

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

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

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

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

في نص HTML:

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

عرض مثال

يوضّح المثال التالي الاتجاهات باستخدام وسائل تنقّل مختلفة بين "هايت آشبري" إلى "أوشن بيتش" في سان فرانسيسكو، كاليفورنيا:

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

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

في نص HTML:

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

عرض مثال

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

سيتم توفير الاتجاهات النصية باستخدام إعداد اللغة المفضّلة في المتصفّح أو اللغة المحدّدة عند تحميل محتوى JavaScript لواجهة برمجة التطبيقات باستخدام المعلَمة language. (لمزيد من المعلومات، راجِع الترجمة.) وفي حالات اتجاهات النقل العام، سيتم عرض الوقت بالمنطقة الزمنية في محطة النقل العام هذه.

يتطابق المثال التالي مع المثال الموضّح أعلاه، ولكنه يتضمّن لوحة <div> تعرض الاتجاهات:

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

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

في نص HTML:

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

عرض مثال

كائن DirectionsResult

عند إرسال طلب للحصول على الاتجاهات إلى DirectionsService، ستتلقّى استجابة تتألف من رمز حالة، بالإضافة إلى نتيجة وهي DirectionsResult. تمثّل السمة DirectionsResult حرفًا حرفيًا في الحقول التالية:

يحتوي السمة geocoded_waypoints[] على صفيف من DirectionsGeocodedWaypoint عنصر، يحتوي كل منها على تفاصيل حول ترميز الموقع الجغرافي للمنشأ والوجهة ونقاط الطريق.
يحتوي الحقل routes[] على صفيف من DirectionsRoute عنصر. ويشير كل مسار إلى طريقة للانتقال من نقطة الانطلاق إلى الوجهة المدرَجة في DirectionsRequest. بشكل عام، يتم عرض مسار واحد فقط لأي طلب، ما لم يتم ضبط حقل "provideRouteAlternatives" للطلب على true، ما قد يؤدي إلى عرض عدة مسارات.

ملاحظة: تم إيقاف via_waypoint في طرق بديلة تم إيقافها نهائيًا. الإصدار 3.27 هو آخر إصدار من واجهة برمجة التطبيقات يضيف المزيد عبر نقاط طرق في مسارات بديلة. بالنسبة إلى الإصدارات 3.28 والإصدارات الأحدث من واجهة برمجة التطبيقات، يمكنك مواصلة تنفيذ الاتجاهات القابلة للسحب باستخدام خدمة "الاتجاهات" من خلال إيقاف سحب المسارات البديلة. يجب أن يكون المسار الرئيسي فقط قابلاً للسحب. يمكن للمستخدمين سحب المسار الرئيسي إلى أن يطابق مسارًا بديلاً.

الاتجاهات ونقاط ترميز المواقع الجغرافية

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

تمثّل السمة DirectionsGeocodedWaypoint حرفًا حرفيًا في الحقول التالية:

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

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

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

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

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

تمثّل السمة DirectionsRoute حرفًا حرفيًا في الحقول التالية:

تحتوي السمة legs[] على مصفوفة من DirectionsLeg كُلّ، ويحتوي كل منها على معلومات عن ساق المسار من موقعَين ضمن المسار المحدّد. ستظهر ساق منفصلة لكل نقطة أو وجهة محدّدة. (سيحتوي المسار الذي لا يحتوي على نقاط طريق على DirectionsLeg واحدة فقط. يتكون كل ساق من سلسلة من DirectionStep.)
تحتوي السمة waypoint_order على مصفوفة تشير إلى ترتيب أي نقاط على المسار في المسار المحسوب. قد تحتوي هذه المصفوفة على ترتيب معدَّل إذا تم تمرير DirectionsRequest optimizeWaypoints: true.
تحتوي السمة overview_path على صفيف من LatLng يمثّل مسارًا تقريبيًا (ناعمًا) للاتجاهات الناتجة.
overview_polyline يحتوي على points كائن واحد يحمل مضمّن polyline مشفّر. هذا الخط الخطي هو مسار تقريبي (ناعم) للاتجاهات الناتجة.
يحتوي bounds على LatLngBounds يشير إلى حدود الخط المتعدد على طول هذا المسار المحدد.
يتضمن الموقع الإلكتروني copyrights نص حقوق الطبع والنشر الذي سيتم عرضه لهذا المسار.
ملاحظة: إذا لم تستخدم عنصر DirectionsRenderer المتوفّر، عليك معالجة هذه المعلومات وعرضها بنفسك.
يحتوي 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، يمكن أن تتوقّع الانتظار لمدة 10 دقائق في حال تفويت الحافلة.
تحتوي السمة line على عنصر TransitLine حرفي يحتوي على معلومات عن خط النقل العام المستخدَم في هذه الخطوة. توفّر السمة TransitLine اسم السطر ومشغِّله، بالإضافة إلى السمات الأخرى الموضَّحة في المواد المرجعية TransitLine.
يحتوي num_stops على عدد المحطات في هذه الخطوة. تشمل محطة الوصول، وليس محطة المغادرة. على سبيل المثال، إذا كانت الاتجاهات تتضمن المغادرة من المحطة "أ" والمرور بها من خلال محطتَي "ب" و"ج"، والوصول إلى المحطة "د"، ستعرض num_stops.

خط رحلة

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

يحتوي name على الاسم الكامل لخط النقل العام هذا. مثل "7 Street Express" أو "14 سانت كروستاون".
short_name يحتوي على الاسم المختصر لخط النقل العام هذا. ويكون هذا الرقم في العادة رقم سطر، مثل "2" أو "M14".
agencies هي مصفوفة تحتوي على عنصر TransitAgency واحد. يقدّم العنصر TransitAgency معلومات حول عامل تشغيل هذا السطر، بما في ذلك السمات التالية:
- يحتوي name على اسم مؤسسة النقل العام.
- تتضمّن السمة phone رقم هاتف مؤسسة النقل العام.
- يحتوي url على عنوان URL لمؤسسة النقل العام.
ملاحظة: إذا كنت تعرض اتجاهات النقل العام يدويًا بدلاً من استخدام الكائن DirectionsRenderer، يجب عرض أسماء وعناوين النقل الخاصة بوكالات النقل العام التي تقدّم خدمات الرحلات.
تتضمّن السمة 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 تلقائيًا.

تنبيه: يؤدي ضبط السمة stopover على false لتجنُّب توقّف التوقّف إلى الحصول على اتجاهات صارمة للغاية في تفسير مسارها. وقد يؤدي ذلك إلى الانعطاف الشديد على المسار أو ZERO_RESULTS في رمز حالة الاستجابة إذا تعذّر على خدمة الاتجاهات إنشاء اتجاهات خلال هذه النقطة.

بشكل تلقائي، تحسب خدمة الاتجاهات مسارًا من خلال نقاط الطريق التي تم تقديمها بالترتيب المذكور. اختياريًا، يمكنك تمرير 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

الحدود والقيود لنقاط الطريق

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

الحد الأقصى لعدد نقاط الطريق المسموح بها عند استخدام خدمة الاتجاهات في واجهة برمجة تطبيقات JavaScript للخرائط هو 25، بالإضافة إلى المصدر والوجهة. ويُرجى العِلم بأنّ هذه الحدود هي نفسها لخدمة الويب الخاصة بالاتجاهات في واجهة برمجة التطبيقات.
بالنسبة إلى خدمة الويب لواجهة برمجة التطبيقات الاتجاهات، يُسمح للعملاء باستخدام 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;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

عرض مثال

تجربة عيّنة من المحتوى

JSFiddle.net CodeSandbox.io Google Cloud Shell