الحصول على الاتجاهات من خلال واجهة برمجة التطبيقات Directions API (القديمة)

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

هذا المنتج في الحالة القديمة. اعتبارًا من أكتوبر 2026، لن يعود بإمكانك تفعيل Directions API (الإصدار القديم) لمشاريع على السحابة الإلكترونية الجديدة في Google Cloud. وستظل المشاريع الحالية متاحة بالكامل. للاستفادة من الميزات الجديدة والأداء المحسّن، يمكنك نقل البيانات إلى Routes API.

بالنسبة إلى عمليات حساب الاتجاهات التي تستجيب في الوقت الفعلي لإدخالات المستخدم (على سبيل المثال، ضمن عنصر واجهة المستخدم)، يمكنك استخدام Directions API (القديمة) أو، إذا كنت تستخدم Maps JavaScript API، يمكنك استخدام خدمة الاتجاهات. للاستخدام من جهة الخادم، يمكنك استخدام عميل Java وعميل Python وعميل Go وعميل Node.js لخدمات "خرائط Google".

باستخدام Directions API (الإصدار القديم)، يمكنك إجراء ما يلي:

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

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

قبل البدء

قبل البدء في استخدام Directions API (الإصدار القديم)، تحتاج إلى مشروع يتضمّن حساب فوترة وتكون واجهة Directions API (الإصدار القديم) مفعَّلة فيه. لمزيد من المعلومات، يُرجى الاطّلاع على الإعداد في وحدة تحكّم Cloud.

إنشاء طلبات Directions API (الإصدار القديم)

يتّخذ طلب Directions API (الإصدار القديم) الشكل التالي:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

حيث يمكن أن تكون قيمة outputFormat أيًا مما يلي:

  • json (يُنصح به) يشير إلى الإخراج بتنسيق JavaScript Object Notation ‏ (JSON)
  • ‫xml تشير إلى أنّ الناتج بتنسيق XML

ملاحظة: يجب أن تكون عناوين URL مُرمَّزة بشكل صحيح لتكون صالحة، ويجب ألا تتجاوز 16,384 حرفًا لجميع خدمات الويب. يُرجى الانتباه إلى هذا الحدّ عند إنشاء عناوين URL.

كما هو معتاد في عناوين URL، يتم الفصل بين جميع المَعلمات باستخدام رمز العطف اللاتيني (&). يجب أن تكون جميع الأحرف المحجوزة (مثل علامة الجمع "+") مرمَّزة بعنوان URL. في ما يلي قائمة بالمَعلمات وقيمها المحتملة.

المعلمات المطلوبة

  • الوجهة

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

  • الأصل

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

    • يجب أن تبدأ أرقام تعريف الأماكن بـ place_id:. يمكنك استرداد أرقام تعريف الأماكن من Geocoding API وPlaces API (بما في ذلك ميزة "الإكمال التلقائي للأماكن"). للاطّلاع على مثال يستخدم أرقام تعريف الأماكن من ميزة "الإكمال التلقائي للأماكن"، يُرجى مراجعة ميزة "الإكمال التلقائي للأماكن" والاتجاهات. لمزيد من المعلومات عن أرقام تعريف الأماكن، يُرجى الاطّلاع على نظرة عامة على رقم تعريف المكان. 

      origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

    • إذا مرّرت عنوانًا، ستعمل خدمة الاتجاهات على ترميز السلسلة جغرافيًا وتحويلها إلى إحداثيات خطوط العرض/الطول لاحتساب الاتجاهات. قد تختلف هذه الإحداثيات عن تلك التي تعرضها Geocoding API، على سبيل المثال مدخل مبنى بدلاً من مركزه. 

      origin=24+Sussex+Drive+Ottawa+ON

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

    • إذا مرّرت إحداثيات، ستتم محاذاة النقطة مع أقرب طريق. ويُفضَّل تمرير رقم تعريف المكان. إذا مرّرت الإحداثيات، تأكَّد من عدم وجود مسافة بين قيمتَي خط العرض وخط الطول. 

      origin=41.43206,-81.38992

    • يجب تنسيق رموز Plus Codes كرمز عالمي أو رمز مركّب. يجب تنسيق رموز Plus Codes كما هو موضّح هنا (يتم إلغاء علامات الجمع في عنوان URL إلى %2B ويتم إلغاء المسافات في عنوان URL إلى %20).

      • الرمز العالمي هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9 هو 849VCWC8%2BR9).
      • الرمز المركّب هو رمز محلي يتألف من 6 أحرف أو أكثر مع موقع جغرافي صريح (CWC8+R9 Mountain View, CA, USA هو CWC8%2BR9%20Mountain%20View%20CA%20USA).
    ملاحظة: لضمان الكفاءة والدقة، استخدِم أرقام تعريف الأماكن إن أمكن. تكون أرقام التعريف هذه واضحة بشكل فريد مثل زوج قيم خطوط العرض/الطول وتوفّر مزايا الترميز الجغرافي للتوجيه، مثل نقاط الوصول ومتغيّرات حركة المرور. على عكس العنوان، لا تتطلّب أرقام التعريف من الخدمة إجراء عملية بحث أو طلب وسيط للحصول على تفاصيل المكان، وبالتالي يكون الأداء أفضل.

المعلمات الاختيارية

  • بدائل

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

  • arrival_time

    تحدّد وقت الوصول المفضّل لاتجاهات النقل العام، بالثواني منذ منتصف الليل، 1 يناير 1970 بالتوقيت العالمي المنسق. يمكنك تحديد departure_time أو arrival_time، ولكن ليس كليهما. يُرجى العِلم أنّه يجب تحديد السمة arrival_time كعدد صحيح.

  • تجنُّب

    تشير إلى أنّ المسارات المحسوبة يجب أن تتجنّب الميزات المُشار إليها. تتيح هذه المَعلمة استخدام الوسيطات التالية:

    • تشير السمة tolls إلى أنّ المسار المحسوب يجب أن يتجنّب الطرق أو الجسور التي تفرض رسوم عبور.
    • تشير السمة highways إلى أنّ المسار المحسوب يجب أن يتجنّب الطرق السريعة.
    • تشير السمة ferries إلى أنّ المسار المحسوب يجب أن يتجنّب العبّارات.
    • تشير السمة indoor إلى أنّ المسار المحسوب يجب أن يتجنّب السلالم الداخلية في اتجاهات المشي والنقل العام.

    يمكن طلب مسار يتجنّب أي مجموعة من رسوم العبور والطرق السريعة والعبّارات من خلال تمرير قيود متعددة إلى مَعلمة التجنّب. على سبيل المثال: 

    avoid=tolls|highways|ferries.

  • departure_time

    تحدّد وقت المغادرة المفضّل. يمكنك تحديد الوقت كعدد صحيح بالثواني منذ منتصف الليل، 1 يناير 1970 بالتوقيت العالمي المنسق. إذا تم تحديد departure_time بعد 9999-12-31T23:59:59.999999999Z، ستعيد واجهة برمجة التطبيقات departure_time إلى 9999-12-31T23:59:59.999999999Z. بدلاً من ذلك، يمكنك تحديد قيمة now، والتي تضبط وقت المغادرة على الوقت الحالي (صحيح لأقرب ثانية). يمكن تحديد وقت المغادرة في حالتَين:

    • بالنسبة إلى الطلبات التي يكون فيها وضع السفر هو النقل العام: يمكنك اختياريًا تحديد departure_time أو arrival_time. إذا لم يتم تحديد أي وقت، يتم ضبط departure_time تلقائيًا على الوقت الحالي (أي يتم ضبط وقت المغادرة تلقائيًا على الوقت الحالي).
    • بالنسبة إلى الطلبات التي يكون فيها وضع السفر هو القيادة: يمكنك تحديد departure_time لتلقّي مسار ومدة الرحلة (حقل الاستجابة: duration_in_traffic) مع مراعاة أحوال حركة المرور. يجب ضبط departure_time على الوقت الحالي أو على وقت في المستقبل. ولا يمكن أن يكون في الماضي.
    ملاحظة: إذا لم يتم تحديد وقت المغادرة، يتم اختيار المسار والمدة استنادًا إلى شبكة الطرق ومتوسط أحوال حركة المرور غير المرتبطة بالوقت. قد تختلف نتائج طلب معيّن بمرور الوقت بسبب التغييرات في شبكة الطرق، ومتوسط أحوال حركة المرور المحدّثة، والطبيعة الموزّعة للخدمة. قد تختلف النتائج أيضًا بين المسارات المتكافئة تقريبًا في أي وقت أو معدل تكرار.
    ملاحظة: إنّ طلبات Distance Matrix التي تحدّد departure_time عندما تكون قيمة mode=driving تقتصر على 100 عنصر كحدّ أقصى لكل طلب. يحدّد عدد نقاط الانطلاق مضروبًا في عدد الوجهات عدد العناصر.

  • language

    اللغة التي سيتم عرض النتائج بها يُرجى العِلم أنّ هذا ينطبق فقط على العناوين التي تم ترميزها جغرافيًا في start_address وend_address، والنص المترجَم في الحقلَين distance وduration (في الأقسام والخطوات)، ووصف المناورات في html_instructions، ولكن ليس على الأسماء والعناوين في html_instructions، والتي يتم تنسيقها بلغتها ونصها المحليين.

    • اطّلِع على قائمة اللغات المتاحة. تعدّل Google اللغات المتاحة بشكل متكرر، لذا قد لا تكون هذه القائمة شاملة.
    • في حال عدم توفير language، تحاول واجهة برمجة التطبيقات استخدام اللغة المفضّلة كما هو محدّد في العنوان Accept-Language.
    • تبذل واجهة برمجة التطبيقات قصارى جهدها لتوفير عنوان شارع يمكن قراءته لكل من المستخدم والسكان المحليين. لتحقيق هذا الهدف، تعرض عناوين الشوارع باللغة المحلية، وتتم كتابتها بأحرف أبجدية أخرى يمكن للمستخدم قراءتها إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها، والتي يتم اختيارها من المكوّن الأول.
    • إذا لم يكن الاسم متاحًا باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابقة.
    • تؤثر اللغة المفضّلة بشكل بسيط في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وفي ترتيب عرضها. تفسّر أداة الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة واحدة ولكن ليس في لغة أخرى. على سبيل المثال، utca وtér هما مرادفان لكلمة "شارع" باللغة الهنغارية.

  • الوضع

    لحساب المسافات والاتجاهات، يمكنك تحديد وسيلة النقل التي تريد استخدامها. يتم استخدام وضع "driving" تلقائيًا. يتم احتساب الاتجاهات تلقائيًا كاتجاهات قيادة. تتوفّر وسائل النقل التالية:

    • تشير القيمة driving (تلقائية) إلى اتجاهات القيادة العادية أو المسافة باستخدام شبكة الطرق.
    • يطلب "walking" الحصول على اتجاهات المشي أو المسافة عبر مسارات المشاة والأرصفة (حيثما كان ذلك متاحًا).
    • bicycling يطلب اتجاهات ركوب الدراجات أو المسافة عبر مسارات الدراجات والشوارع المفضّلة (حيثما كان ذلك متاحًا).
    • transit يطلب الاتجاهات أو المسافة باستخدام مسارات النقل العام (حيثما تتوفر). إذا ضبطت الوضع على "النقل"، يمكنك تحديد departure_time أو arrival_time بشكل اختياري. إذا لم يتم تحديد أي وقت، يتم ضبط departure_time تلقائيًا على الوقت الحالي (أي يتم ضبط وقت المغادرة تلقائيًا على الوقت الحالي). يمكنك أيضًا تضمين transit_mode و/أو transit_routing_preference اختياريًا. تتوفّر رحلات النقل العام لمدة تصل إلى 7 أيام في الماضي أو تصل إلى 100 يوم في المستقبل، وذلك حسب توفّر معلومات النقل العام التي يقدّمها مزوّدو البيانات. تتغيّر جداول النقل العام بشكل متكرّر، وقد تتغيّر رحلات النقل العام المتاحة بمرور الوقت، ولا يمكن ضمان تقديم نتائج متّسقة للتوقّعات قبل وقت طويل.
    ملاحظة: قد لا تتضمّن اتجاهات المشي واتجاهات الدراجات أحيانًا مسارات واضحة للمشاة أو راكبي الدراجات، لذا ستعرض هذه الاتجاهات تحذيرات في النتيجة التي يجب عرضها للمستخدم.

  • المنطقة

    رمز المنطقة، ويتم تحديده كقيمة مكوّنة من حرفَين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD). تتطابق معظم رموز نطاقات المستوى الأعلى لرمز البلد مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) الذي يمثّل المملكة المتحدة هو "uk"‏ (‎.co.uk)، في حين أنّ رمز المنظمة الدولية للمعايير (ISO) 3166-1 الخاص بها هو "gb" (وهو من الناحية الفنية يمثّل "كيان" "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").

  • traffic_model

    تحدّد هذه المَعلمة الافتراضات التي يجب استخدامها عند احتساب الوقت في حركة المرور. يؤثر هذا الإعداد في القيمة التي يتم عرضها في حقل duration_in_traffic في الاستجابة، والذي يحتوي على الوقت المتوقّع في حركة المرور استنادًا إلى المتوسطات السابقة. يمكن تحديد المَعلمة traffic_model فقط لاتجاهات القيادة عندما يتضمّن الطلب departure_time. القيم المتاحة لهذه المَعلمة هي:

    • best_guess (تلقائي) تشير إلى أنّ القيمة المعروضة duration_in_traffic يجب أن تكون أفضل تقدير لمدة الرحلة بالنظر إلى ما هو معروف عن كلّ من أحوال حركة المرور السابقة وحركة المرور المباشرة. تزداد أهمية معلومات الكثافة في حركة المرور في الوقت الفعلي كلما اقترب departure_time من الوقت الحالي.
    • تشير السمة pessimistic إلى أنّ قيمة duration_in_traffic التي يتم عرضها يجب أن تكون أطول من مدة الرحلة الفعلية في معظم الأيام، مع أنّ بعض الأيام التي تشهد أحوال حركة مرور سيئة بشكل خاص قد تتجاوز هذه القيمة.
    • تشير السمة optimistic إلى أنّ قيمة duration_in_traffic التي يتم عرضها يجب أن تكون أقصر من مدة الرحلة الفعلية في معظم الأيام، مع أنّ بعض الأيام التي تكون فيها أحوال حركة المرور جيدة بشكل خاص قد تكون أسرع من هذه القيمة.

    ستوفّر القيمة التلقائية لـ best_guess التوقّعات الأكثر فائدة للغالبية العظمى من حالات الاستخدام. من الممكن أن يكون توقّع مدة الرحلة في best_guess أقصر من optimistic، أو على العكس، أطول من pessimistic، وذلك بسبب الطريقة التي يدمج بها نموذج التنبؤ في best_guess معلومات حركة المرور المباشرة.

  • transit_mode

    تحدّد هذه السمة وسيلة نقل واحدة أو أكثر مفضّلة. لا يمكن تحديد هذه المَعلمة إلا لاتجاهات النقل العام. تتيح المَعلمة استخدام الوسيطات التالية:

    • تشير السمة bus إلى أنّ المسار المحسوب يجب أن يفضّل السفر بالحافلة.
    • تشير السمة subway إلى أنّ المسار المحسوب يجب أن يفضّل التنقّل باستخدام مترو الأنفاق.
    • تشير السمة train إلى أنّ المسار المحسوب يجب أن يفضّل السفر بالقطار.
    • تشير القيمة tram إلى أنّ المسار المحسوب يجب أن يفضّل السفر بالترام والقطار الخفيف.
    • تشير السمة rail إلى أنّ المسار المحسوب يجب أن يفضّل السفر بالقطار والترام والقطار الخفيف ومترو الأنفاق. وهذا يعادل transit_mode=train|tram|subway.

  • transit_routing_preference

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

    • تشير السمة less_walking إلى أنّ المسار المحسوب يجب أن يفضّل المشي لمسافات محدودة.
    • تشير السمة fewer_transfers إلى أنّ المسار المحسوب يجب أن يفضّل عددًا محدودًا من عمليات النقل.

  • وحدتان

    يحدّد نظام الوحدات الذي سيتم استخدامه عند عرض النتائج.

    تحتوي نتائج الاتجاهات على نص ضمن حقول المسافة التي قد يتم عرضها للمستخدم للإشارة إلى مسافة "خطوة" معيّنة من المسار. يستخدم هذا النص تلقائيًا نظام الوحدات في بلد أو منطقة نقطة الانطلاق.

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

    • تحدّد السمة metric استخدام النظام المتري. يتم عرض المسافات النصية بالكيلومتر والمتر.
    • تشير القيمة imperial إلى استخدام النظام الإمبراطوري (الإنجليزي). يتم عرض المسافات النصية باستخدام الأميال والأقدام.
    ملاحظة: لا يؤثر إعداد نظام الوحدات هذا إلا في النص المعروض ضمن حقول المسافة. تحتوي حقول المسافة أيضًا على قيم يتم التعبير عنها دائمًا بالأمتار.

  • نقاط الطريق

    تنبيه: يتم تحصيل رسوم أعلى مقابل الطلبات التي تستخدم أكثر من 10 نقاط على المسار (بين 11 و25) أو تحسين النقاط على المسار. مزيد من المعلومات حول الفوترة لمنتجات "منصة خرائط Google"

    تحدّد مصفوفة من المواقع الجغرافية الوسيطة التي يجب تضمينها على طول المسار بين نقطتَي الانطلاق والوجهة كمواقع جغرافية للمرور أو التوقف. تغيّر نقاط المسار مسارًا من خلال توجيهه عبر المواقع الجغرافية المحدّدة. تتيح واجهة برمجة التطبيقات النقاط على المسار لوسائل النقل التالية: القيادة والمشي وركوب الدراجات، ولكن ليس النقل العام. يمكنك تقديم موقع جغرافي واحد أو أكثر مفصولاً بحرف الخط العمودي (| أو %7C)، على شكل رقم تعريف مكان أو عنوان أو إحداثيات خطوط العرض/الطول. تحسب خدمة الاتجاهات تلقائيًا مسارًا باستخدام نقاط المسار بالترتيب الذي يتم تقديمها به. تكون الأولوية لتحليل قيمة النقطة على المسار هي رقم تعريف المكان، ثم إحداثيات خطوط العرض/الطول، ثم العنوان.

    • إذا مرّرت رقم تعريف مكان، يجب أن تسبقه بـ place_id:. يمكنك استرداد أرقام تعريف الأماكن من Geocoding API وPlaces API (بما في ذلك ميزة "الإكمال التلقائي للأماكن"). للاطّلاع على مثال يستخدم أرقام تعريف الأماكن من ميزة "الإكمال التلقائي للأماكن"، يُرجى مراجعة ميزة "الإكمال التلقائي للأماكن" والاتجاهات. لمزيد من المعلومات عن أرقام تعريف الأماكن، يُرجى الاطّلاع على نظرة عامة على رقم تعريف المكان.
      لتحقيق الكفاءة والدقة، استخدِم أرقام تعريف الأماكن عندما يكون ذلك ممكنًا. تكون أرقام التعريف هذه واضحة بشكل فريد مثل زوج قيم خطوط العرض/الطول وتوفّر مزايا الترميز الجغرافي للتوجيه، مثل نقاط الوصول ومتغيّرات حركة المرور. على عكس العنوان، لا تتطلّب أرقام التعريف من الخدمة إجراء عملية بحث أو طلب وسيط للحصول على تفاصيل المكان، وبالتالي يكون الأداء أفضل.
    • إذا مرّرت إحداثيات خطوط العرض/الطول، تنتقل القيم مباشرةً إلى خادم الواجهة الأمامية لحساب الاتجاهات بدون ترميز جغرافي. يتم تثبيت النقاط على الطرق وقد لا توفّر الدقة التي يحتاجها تطبيقك. استخدِم الإحداثيات عندما تكون واثقًا من أنّ القيم تحدّد بدقة النقاط التي يحتاجها تطبيقك للتوجيه بدون النظر إلى نقاط الوصول المحتملة أو تفاصيل الترميز الجغرافي الإضافية. تأكَّد من استخدام فاصلة (%2C) وليس مسافة (%20) للفصل بين قيم خطوط العرض والطول.
    • إذا مرّرت عنوانًا، ستعمل خدمة "الاتجاهات" على الترميز الجغرافي للسلسلة وتحويلها إلى إحداثيات خطوط العرض/الطول لاحتساب الاتجاهات. إذا كانت قيمة العنوان غامضة، قد تؤدي القيمة إلى إجراء بحث لإزالة الغموض عن العناوين المشابهة. على سبيل المثال، قد تكون القيمة "شارع 1" قيمة كاملة أو قيمة جزئية لـ "شارع 1 شمال شرق" أو "شارع 1 جنوب شرق". قد تختلف هذه النتيجة عن تلك التي تعرضها Geocoding API. يمكنك تجنُّب التفسيرات الخاطئة المحتملة باستخدام أرقام تعريف الأماكن.
    • بدلاً من ذلك، يمكنك تقديم مجموعة نقاط مرمّزة باستخدام خوارزمية الخطوط المتعدّدة المرمّزة. ستجد أنّ المجموعة المرمّزة مفيدة لعدد كبير من النقاط على المسار، لأنّ عنوان URL يكون أقصر بكثير. يبلغ الحد الأقصى لعدد الأحرف في عنوان URL لجميع خدمات الويب 16384 حرفًا.
      • يجب أن تبدأ الخطوط المتعدّدة المرمّزة بـ enc: وأن تتبعها نقطتان رأسيتان (:)، على سبيل المثال: waypoints=enc:gfo}EtohhU:.
      • يمكنك أيضًا تضمين عدة خطوط متعدّدة مُرمَّزة، مع الفصل بينها باستخدام حرف الخط العمودي (|). على سبيل المثال، waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:| via:enc:udymA{~bxM:
    التأثير في المسارات من خلال نقاط التوقف ونقاط المرور

    لكل نقطة على المسار في الطلب، يُلحق ردّ الاتجاهات إدخالاً بمصفوفة legs لتقديم تفاصيل عن محطات التوقف في ذلك الجزء من الرحلة.

    إذا أردت التأثير في المسار باستخدام نقاط على المسار بدون إضافة محطة توقّف، أضِف البادئة via: إلى النقطة على المسار. لن تؤدي النقاط على المسار المسبوقة بـ via: إلى إضافة إدخال إلى مصفوفة legs، ولكن سيتم توجيه الرحلة عبر النقطة على المسار.

    يعدّل عنوان URL التالي الطلب السابق بحيث يتم توجيه الرحلة عبر ليكسينغتون بدون توقف: 

    https://maps.googleapis.com/maps/api/directions/json?
origin=Boston,MA&destination=Concord,MA
&waypoints=Charlestown,MA|via:Lexington,MA

    تكون البادئة via: أكثر فعالية عند إنشاء المسارات استجابةً لسحب المستخدم لنقاط المسار على الخريطة. يتيح ذلك للمستخدم الاطّلاع على المسار النهائي في الوقت الفعلي ويساعد في ضمان وضع النقاط على المسار في أماكن يمكن الوصول إليها من خلال Directions API.

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

    تحسب خدمة الاتجاهات تلقائيًا مسارًا من خلال النقاط على المسار المقدَّمة بالترتيب المحدَّد. يمكنك اختياريًا تمرير optimize:true كوسيطة أولى ضمن مَعلمة النقاط على المسار للسماح لخدمة "اتجاهات السير" بتحسين المسار المقدَّم من خلال إعادة ترتيب النقاط على المسار بترتيب أكثر كفاءة. (هذا التحسين هو تطبيق لمسألة البائع المتجوّل). تُعدّ مدة الرحلة العامل الأساسي الذي يتم تحسينه، ولكن قد يتم أخذ عوامل أخرى في الاعتبار عند تحديد المسار الأكثر كفاءة، مثل المسافة وعدد المنعطفات وغيرها الكثير. يجب أن تكون جميع النقاط على المسار محطات توقّف لخدمة "الاتجاهات" من أجل تحسين مسارها.

    إذا طلبت من خدمة "الاتجاهات" تحسين ترتيب نقاط المسار، سيتم عرض ترتيبها في حقل waypoint_order ضمن عنصر المسارات. يعرض الحقل waypoint_order قيمًا تستند إلى الصفر.

    يحسب المثال التالي رحلة برية من أديلايد في جنوب أستراليا إلى كل منطقة من مناطق النبيذ الرئيسية في جنوب أستراليا باستخدام ميزة تحسين المسار. 

    https://maps.googleapis.com/maps/api/directions/json?
origin=Adelaide,SA&destination=Adelaide,SA
&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA

    سيشير فحص المسار المحسوب إلى أنّ عملية الحساب تستخدم نقاط المسار بالترتيب التالي: 

    "waypoint_order": [ 3, 2, 0, 1 ]
    تنبيه: يتم تحصيل رسوم أعلى مقابل الطلبات التي تستخدم ميزة تحسين النقاط على المسار. مزيد من المعلومات حول كيفية فوترة منتجات "منصة خرائط Google"

الخطوات التالية

أمثلة على الاتجاهات

الردود على طلبات الاتجاهات