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

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

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

نظرة عامة

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

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

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

البدء

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

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

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

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

التسعير

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

السياسات

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

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

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

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

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

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

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

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

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

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

حالة طلب الاتجاهات

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

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

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

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

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

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

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

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

ملاحظة: تمت إعادة تسمية الكائن القديم 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 الوقت المحدّد ككائن JavaScript Date.
- 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 الغرب" مدة "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 الوقت المحدّد ككائن JavaScript Date.
- 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`	ستعرض جميع المركبات الأخرى هذا النوع.

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

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

عرض مثال

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

وكما هو مذكور في طلب الاتجاهات، يمكنك أيضًا تحديد نقاط الطرق (من النوع 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

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

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

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

عرض مثال

تجربة النموذج

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell