الحصول على مفتاح Maps Demo Key: يمكنك تجربة ميزات محدّدة من Maps JavaScript API و"حزمة أدوات خرائط Google الجاهزة للأماكن" بدون أي تكلفة باستخدام مفتاح Maps Demo Key، وبدون الحاجة إلى إدخال معلومات الفوترة.

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

خدمة الاتجاهات (الإصدار القديم)

المطوّرون في المنطقة الاقتصادية الأوروبية

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

نظرة عامة

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

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

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

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

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

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

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

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

الأسعار

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

السياسات

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

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

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

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

يحتوي الكائن الحرفي DirectionsRequest على الحقول التالية:

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

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

‫origin (مطلوبة): تحدّد الموقع الجغرافي لنقطة الانطلاق التي يتم احتساب الاتجاهات منها. يمكن تحديد هذه القيمة على شكل String (مثلاً، "القاهرة، مصر") أو على شكل قيمة LatLng أو على شكل عنصر Place. إذا كنت تستخدم عنصر مكان، يمكنك تحديد رقم تعريف المكان أو سلسلة طلب بحث أو موقع جغرافي في LatLng. يمكنك استرداد أرقام تعريف الأماكن من خدمات "الترميز الجغرافي" و"البحث عن الأماكن" و"الإكمال التلقائي للأماكن" في Maps JavaScript API. للاطّلاع على مثال يستخدم أرقام تعريف الأماكن من ميزة "الإكمال التلقائي للأماكن"، يُرجى مراجعة ميزة الإكمال التلقائي للأماكن والاتجاهات.
‫destination (مطلوبة) تحدّد الموقع الجغرافي النهائي الذي سيتم احتساب الاتجاهات إليه. الخيارات هي نفسها المتاحة لحقل origin الموضّح أعلاه.
تحدّد المَعلمة travelMode (مطلوبة) وسيلة النقل التي يجب استخدامها عند احتساب الاتجاهات. يتم تحديد القيم الصالحة في أوضاع السفر أدناه.
transitOptions (اختياري) يحدّد القيم التي تنطبق فقط على الطلبات التي تكون فيها قيمة travelMode هي TRANSIT. يتم وصف القيم الصالحة في قسم خيارات النقل أدناه.
drivingOptions (اختياري) يحدّد القيم التي تنطبق فقط على الطلبات التي تكون فيها قيمة travelMode هي DRIVING. يتم وصف القيم الصالحة في خيارات القيادة أدناه.
unitSystem (اختياري) يحدّد نظام الوحدات الذي يجب استخدامه عند عرض النتائج. يتم تحديد القيم الصالحة في أنظمة الوحدات أدناه.
waypoints[] (اختيارية) تحدّد مصفوفة من DirectionsWaypoint. تغيّر النقاط على المسار المسار من خلال توجيهه عبر المواقع الجغرافية المحدّدة. يتم تحديد نقطة على المسار ككائن حرفي مع الحقول الموضّحة أدناه:
- تحدّد السمة location الموقع الجغرافي للنقطة على المسار، كقيمة LatLng أو كعنصر مكان أو كقيمة String سيتم ترميزها جغرافيًا.
- ‫stopover هي قيمة منطقية تشير إلى أنّ النقطة على المسار هي محطة توقّف على المسار، ما يؤدي إلى تقسيم المسار إلى مسارَين.
(لمزيد من المعلومات عن النقاط على المسار، يُرجى الاطّلاع على قسم استخدام النقاط على المسار في المسارات أدناه).
optimizeWaypoints (اختيارية) تحدّد أنّ المسار الذي يستخدم waypoints المقدَّمة يمكن تحسينه من خلال إعادة ترتيب النقاط على المسار بترتيب أكثر كفاءة. إذا كانت القيمة true، ستعرض خدمة الاتجاهات waypoints المُعاد ترتيبها في حقل waypoint_order.(لمزيد من المعلومات، يُرجى الاطّلاع على استخدام النقاط على المسار في المسارات أدناه).
provideRouteAlternatives (اختيارية) عند ضبطها على true، تحدّد أنّ خدمة الاتجاهات قد توفّر أكثر من مسار بديل في الاستجابة. يُرجى العِلم أنّ توفير مسارات بديلة قد يؤدي إلى زيادة وقت الاستجابة من الخادم. لا تتوفّر هذه الميزة إلا للطلبات التي لا تتضمّن نقاط مسار وسيطة.
avoidFerries (اختيارية): عند ضبطها على true، تشير إلى أنّ المسارات المحسوبة يجب أن تتجنّب العبّارات، إن أمكن.
avoidHighways (اختيارية) عند ضبطها على true تشير إلى أنّ المسارات المحسوبة يجب أن تتجنّب الطرق السريعة الرئيسية، إن أمكن.
avoidTolls (اختيارية) عند ضبطها على true تشير إلى أنّ المسارات المحسوبة يجب أن تتجنّب الطرق برسوم عبور، إن أمكن.
region (اختيارية) تحدّد رمز المنطقة، ويتم تحديدها كقيمة من حرفَين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD). (لمزيد من المعلومات، يُرجى الاطّلاع على قسم الانحياز إلى منطقة معيّنة أدناه).

ملاحظة: تم إيقاف الحقل 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 (Default) تشير إلى اتجاهات القيادة العادية باستخدام شبكة الطرق.
‫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 Maps Platform Premium، إذا أدرجت 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 Maps API نتائج العناوين المتأثرة بالنطاق (المنطقة أو البلد) الذي حمّلت منه برنامج تمهيد JavaScript. (بما أنّ معظم المستخدمين يحمّلون https://maps.googleapis.com/، يتم ضبط نطاق ضمني للولايات المتحدة). إذا حمّلت برنامج الإقلاع من نطاق مختلف متوافق، ستحصل على نتائج متأثرة بهذا النطاق. على سبيل المثال، قد تؤدي عمليات البحث عن "سان فرانسيسكو" إلى عرض نتائج مختلفة من التطبيقات التي تحمّل https://maps.googleapis.com/ (الولايات المتحدة) عن تلك التي تحمّل http://maps.google.es/ (إسبانيا).

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

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

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

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

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

يتطلب بدء طلب اتجاهات إلى DirectionsService باستخدام طريقة route() تمرير دالة رد اتصال يتم تنفيذها عند اكتمال طلب الخدمة. ستعرض دالة الاستدعاء هذه DirectionsResult ورمز DirectionsStatus في الاستجابة.

حالة طلب البحث عن الاتجاهات

قد يعرض DirectionsStatus القيم التالية:

تشير السمة OK إلى أنّ الردّ يحتوي على قيمة صالحة للسمة DirectionsResult.
تشير السمة NOT_FOUND إلى أنّه تعذّر ترميز موقع جغرافي واحد على الأقل من المواقع الجغرافية المحدّدة في نقطة الانطلاق أو الوجهة أو نقاط المسار في الطلب.
تشير القيمة ZERO_RESULTS إلى أنّه تعذّر العثور على مسار بين نقطة الانطلاق والوجهة.
تشير السمة MAX_WAYPOINTS_EXCEEDED إلى أنّه تم تقديم عدد كبير جدًا من حقول DirectionsWaypoint في DirectionsRequest. يمكنك الاطّلاع على القسم أدناه حول الحدود القصوى لنقاط المسار.
تشير السمة MAX_ROUTE_LENGTH_EXCEEDED إلى أنّ المسار المطلوب طويل جدًا ولا يمكن معالجته. يحدث هذا الخطأ عند عرض اتجاهات أكثر تعقيدًا. حاوِل تقليل عدد النقاط على المسار أو الانعطافات أو التعليمات.
تشير السمة INVALID_REQUEST إلى أنّ السمة DirectionsRequest المقدَّمة غير صالحة. الأسباب الأكثر شيوعًا لرمز الخطأ هذا هي الطلبات التي لا تتضمّن نقطة انطلاق أو وجهة، أو طلبات النقل العام التي تتضمّن نقاطًا على المسار.
يشير الرمز OVER_QUERY_LIMIT إلى أنّ صفحة الويب قد أرسلت عددًا كبيرًا جدًا من الطلبات خلال الفترة الزمنية المسموح بها.
تشير القيمة REQUEST_DENIED إلى أنّه لا يُسمح لصفحة الويب باستخدام خدمة الاتجاهات.
تشير السمة UNKNOWN_ERROR إلى أنّه تعذّرت معالجة طلب الاتجاهات بسبب خطأ في الخادم. قد ينجح الطلب إذا حاولت مرة أخرى.

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

عرض DirectionsResult

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

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

أنشِئ عنصر 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>

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

يوضّح المثال التالي الاتجاهات باستخدام وسائل نقل مختلفة بين Haight-Ashbury وOcean Beach في سان فرانسيسكو، كاليفورنيا:

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" إلى عرض مطابقة جزئية لكل من Henry Street وHenrietta Street. يُرجى العِلم أنّه إذا كان الطلب يتضمّن مكوّن عنوان مكتوبًا بشكل غير صحيح، قد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. سيتم أيضًا وضع علامة على الاقتراحات التي يتم عرضها بهذه الطريقة على أنّها مطابقة جزئية.
place_idهو معرّف فريد لمكان معيّن، ويمكن استخدامه مع Google APIs الأخرى. على سبيل المثال، يمكنك استخدام place_id مع مكتبة Google Places API للحصول على تفاصيل عن نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين والمزيد. اطّلِع على نظرة عامة على رقم تعريف المكان.
‫types[] هي مصفوفة تشير إلى نوع النتيجة التي تم عرضها. تحتوي هذه المصفوفة على مجموعة من صفر أو أكثر من العلامات التي تحدّد نوع الميزة التي تم عرضها في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي لـ "شيكاغو" "locality" (محلية) للإشارة إلى أنّ "شيكاغو" هي مدينة، ويعرض أيضًا "political" (سياسية) للإشارة إلى أنّها كيان سياسي.

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

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

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

‫DirectionsRoute هو كائن حرفي يتضمّن الحقول التالية:

يحتوي legs[] على مصفوفة من عناصر DirectionsLeg، يحتوي كل منها على معلومات حول جزء من المسار، من موقعَين جغرافيَين ضمن المسار المحدّد. سيظهر جزء منفصل لكل نقطة على المسار أو وجهة محدّدة. (سيحتوي المسار الذي لا يتضمّن نقاطًا على المسار على DirectionsLeg واحد بالضبط). يتألف كل جزء من سلسلة من DirectionStep.
يحتوي waypoint_order على مصفوفة تشير إلى ترتيب أي نقاط على المسار في المسار المحسوب. قد تحتوي هذه المصفوفة على ترتيب معدَّل إذا تم تمرير DirectionsRequest optimizeWaypoints: true.
يحتوي overview_path على مصفوفة من LatLng التي تمثّل مسارًا تقريبيًا (مبسّطًا) للاتجاهات الناتجة.
يحتوي overview_polyline على عنصر points واحد يتضمّن تمثيلاً للخطوط المتعدّدة المرمّزة للمسار. هذا الخط المتعدّد هو مسار تقريبي (مبسّط) للاتجاهات الناتجة.
يحتوي bounds على LatLngBounds يشير إلى حدود الخطوط المتعدّدة على طول هذا المسار المحدّد.
يحتوي copyrights على نص حقوق الطبع والنشر الذي سيتم عرضه لهذا المسار.
ملاحظة: إذا لم تستخدم عنصر 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 لنقطة انطلاق هذا الجزء من الرحلة. بما أنّ خدمة الويب Directions Web Service تحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب خيار نقل (عادةً ما يكون طريقًا) عند نقطتَي البداية والنهاية، قد يختلف start_location عن نقطة الانطلاق المقدَّمة لهذا الجزء من الرحلة إذا لم يكن هناك طريق بالقرب من نقطة الانطلاق مثلاً.
تحتوي السمة end_location على LatLng وجهة هذا الجزء من الرحلة. بما أنّ DirectionsService تحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب خيار نقل (عادةً ما يكون طريقًا) عند نقطتَي البداية والنهاية، قد تختلف قيمة end_location عن الوجهة المقدَّمة لهذا الجزء من الرحلة إذا لم يكن هناك طريق بالقرب من الوجهة مثلاً.
start_address يحتوي على العنوان الذي يمكن لشخص عادي قراءته (عادةً عنوان شارع) لبداية هذا الجزء.

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

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

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

‫DirectionsStep هو الوحدة الأكثر دقة في مسار الاتجاه، ويحتوي على خطوة واحدة تصف تعليمات محدّدة في الرحلة. مثلاً، "انعطِف يسارًا عند شارع W. 4th St." لا تصف الخطوة التعليمات فحسب، بل تحتوي أيضًا على معلومات المسافة والمدة المتعلقة بكيفية ارتباط هذه الخطوة بالخطوة التالية. على سبيل المثال، قد تحتوي الخطوة التي يُشار إليها باسم "الاندماج في الطريق السريع 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 Avenue Express" أو "14th St Crosstown".
يحتوي short_name على الاسم المختصر لخط النقل العام هذا. يكون هذا عادةً رقم خط، مثل "2" أو "M14".
‫agencies هي مصفوفة تحتوي على عنصر TransitAgency واحد. يوفّر العنصر TransitAgency معلومات عن مشغّل هذا الخط، بما في ذلك السمات التالية:
- ‫name يحتوي على اسم مؤسسة النقل العام.
- يحتوي الحقل phone على رقم هاتف مؤسسة النقل العام.
- يحتوي url على عنوان URL الخاص بمؤسسة النقل العام.
ملاحظة: في حال عرض اتجاهات النقل العام يدويًا بدلاً من استخدام الكائن DirectionsRenderer، يجب عرض أسماء وعناوين URL لمؤسسات النقل العام التي تقدّم نتائج الرحلة.
يحتوي url على عنوان URL لخط النقل العام هذا كما هو مقدَّم من مؤسسة النقل العام.
يحتوي icon على عنوان URL للرمز المرتبط بهذا السطر. ستستخدم معظم المدن رموزًا عامة تختلف حسب نوع المركبة. تحتوي بعض خطوط النقل العام، مثل نظام مترو أنفاق نيويورك، على رموز خاصة بهذا الخط.
يحتوي color على اللون الشائع استخدامه في اللافتات الخاصة بوسيلة النقل العام هذه. سيتم تحديد اللون كسلسلة ست عشرية، مثل: ‎#FF0033.
يحتوي text_color على لون النص المستخدَم عادةً للافتات هذا الخط. سيتم تحديد اللون كسلسلة سداسية عشرية.
يحتوي vehicle على عنصر Vehicle يتضمّن السمات التالية:
- يحتوي العمود name على اسم المركبة في هذا السطر. مثال: "Subway."
- يحتوي العمود 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`	وستعرض جميع المركبات الأخرى هذا النوع.

Inspecting DirectionsResults

قد يتم فحص مكوّنات 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>

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

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

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

يتألف waypoint من الحقول التالية:

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

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

تحسب خدمة الاتجاهات تلقائيًا مسارًا من خلال النقاط على المسار المقدَّمة بالترتيب المحدّد. يمكنك اختياريًا تمرير 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;index.ts

JavaScript

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

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

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

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

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

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

      summaryPanel.innerHTML = "";

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

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

window.initMap = initMap;index.js

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

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

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

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

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

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

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

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

TypeScript

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

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

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

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

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

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

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

  if (!myroute) {
    return;
  }

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

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

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

JavaScript

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

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

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

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

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

  if (!myroute) {
    return;
  }

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

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

window.initMap = initMap;index.js

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

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

نظرة عامة

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

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

الأسعار

السياسات

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

أوضاع السفر

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

خيارات القيادة

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

تحديد المنطقة الجغرافية المفضّلة للاتجاهات

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

حالة طلب البحث عن الاتجاهات

عرض DirectionsResult

عنصر DirectionsResult

النقاط على المسار المرمّزة جغرافيًا في الاتجاهات

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

أجزاء المسار

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

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

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

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

نوع المركبة

Inspecting DirectionsResults

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

TypeScript

JavaScript

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

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

TypeScript

JavaScript

خدمة الاتجاهات (الإصدار القديم)