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

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

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

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

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

أمثلة على الطلبات

يعرض الطلب التالي اتجاهات القيادة من تورونتو، أونتاريو إلى مونتريال، كيبيك.

عنوان URL

https://maps.googleapis.com/maps/api/directions/json?destination=Montreal
  &origin=Toronto
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&key=YOUR_API_KEY'

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

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?avoid=highways
  &destination=Montreal
  &mode=bicycling
  &origin=Toronto
  &key=YOUR_API_KEYYOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&avoid=highways&mode=bicycling&key=YOUR_API_KEY'YOUR_API_KEY'

يبحث الطلب التالي عن اتجاهات النقل العام من بروكلين، نيويورك إلى كوينز، نيويورك. لا يحدّد الطلب قيمة departure_time، لذا يتم ضبط وقت المغادرة تلقائيًا على الوقت الحالي:

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=Queens
  &mode=transit
  &origin=Brooklyn
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&keyYOUR_API_KEY'

يتضمّن طلب النقل العام التالي وقت مغادرة محدّدًا.

ملاحظة: في هذا المثال، تم تحديد وقت المغادرة في 30 يوليو 2012 الساعة 09:45 صباحًا. لتجنُّب حدوث خطأ، يجب تغيير المَعلمة إلى وقت في المستقبل قبل إرسال الطلب.

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?departure_time=1343641500
  &destination=Queens
  &mode=transit
  &origin=Brooklyn
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&departure_time=1343641500&key=YOUR_API_KEY'

يستخدم الطلب التالي رموز Plus Codes لعرض اتجاهات القيادة من H8MW+WP إلى GCG2+3M في كولكاتا، الهند.

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=GCG2%2B3M%20Kolkata%20India
  &origin=H8MW%2BWP%20Kolkata%20India
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=H8MW%2BWP%20Kolkata%20India&destination=GCG2%2B3M%20Kolkata%20India&key=YOUR_API_KEY'

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

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=place_id%3AChIJA01I-8YVhkgRGJb0fW4UX7Y
  &origin=place_id%3AChIJ685WIFYViEgRHlHvBbiD5nE
  &keyYOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=place_id%3AChIJ685WIFYViEgRHlHvBbiD5nE&destination=place_id%3AChIJA01I-8YVhkgRGJb0fW4UX7Y&key=YOUR_API_KEY'

وسائل النقل

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

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

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

معلومات حركة المرور

يتم استخدام معلومات حركة المرور عند استيفاء جميع الشروط التالية (هذه هي الشروط المطلوبة لتلقّي الحقل duration_in_traffic في ردّ الاتجاهات):

إذا كانت مَعلمة وسيلة النقل mode هي driving أو لم يتم تحديدها (driving هي وسيلة النقل التلقائية)
يتضمّن الطلب مَعلمة departure_time صالحة. يمكن ضبط departure_time على الوقت الحالي أو على وقت في المستقبل. ولا يمكن أن يكون في الماضي.
لا يتضمّن الطلب نقاط توقّف على المسار. إذا كان الطلب يتضمّن نقاطًا على المسار، أضِف البادئة via: إلى كل نقطة على المسار للتأثير في المسار مع تجنُّب التوقفات. على سبيل المثال:
```
&waypoints=via:San Francisco|via:Mountain View|...
```

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

يبدأ عنوان URL التالي طلب "اتجاهات" لرحلة من بوسطن، ماساتشوستس إلى كونكورد، ماساتشوستس، عبر تشارلزتاون وليكسينغتون. يتضمّن الطلب وقت مغادرة يستوفي جميع المتطلبات لعرض حقل duration_in_traffic في استجابة الاتجاهات.

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?departure_time=now
  &destination=Concord%2C%20MA
  &origin=Boston%2C%20MA
  &waypoints=via%3ACharlestown%2CMA%7Cvia%3ALexington%2CMA
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Boston%2C%20MA&destination=Concord%2C%20MA&waypoints=via%3ACharlestown%2CMA%7Cvia%3ALexington%2CMA&departure_time=now&key=YOUR_API_KEY'

نقاط الطريق

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

حدِّد المواقع الجغرافية في المَعلمة `waypoints`.

يمكنك تقديم موقع جغرافي واحد أو أكثر مفصولاً بحرف الخط العمودي (| أو %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:

يبدأ عنوان URL التالي طلب "اتجاهات" لرحلة بين بوسطن، ماساتشوستس وكونكورد، ماساتشوستس مع محطات توقف في تشارلزتاون وليكسينغتون، بهذا الترتيب. يستخدم المثال العناوين التالية:

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=Concord%2C%20MA
  &origin=Boston%2C%20MA
  &waypoints=via%3ACharlestown%2CMA%7Cvia%3ALexington%2CMA
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Boston%2C%20MA&destination=Concord%2C%20MA&waypoints=via%3ACharlestown%2CMA%7Cvia%3ALexington%2CMA&key=YOUR_API_KEY'

التأثير في المسارات من خلال نقاط التوقف ونقاط المرور

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

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

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

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=Concord%2C%20MA
  &origin=Boston%2C%20MA
  &waypoints=Charlestown%2CMA%7Cvia%3ALexington%2CMA
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Boston%2C%20MA&destination=Concord%2C%20MA&waypoints=Charlestown%2CMA%7Cvia%3ALexington%2CMA&key=YOUR_API_KEY'

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

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

يطلب عنوان URL التالي نقاطًا على المسار باستخدام إحداثيات خطوط العرض/الطول:

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=Perth%2C%20AU
  &origin=Sydney%2C%20AU
  &waypoints=via%3A-37.81223%2C144.96254%7Cvia%3A-34.92788%2C138.60008
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Sydney%2C%20AU&destination=Perth%2C%20AU&waypoints=via%3A-37.81223%2C144.96254%7Cvia%3A-34.92788%2C138.60008&key=YOUR_API_KEY'

في ما يلي الطلب نفسه، باستخدام خطوط متعدّدة مرمّزة:

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=Perth%2C%20AU
  &origin=Sydney%2C%20AU
  &waypoints=via%3Aenc%3AlexeF%7B~wsZejrPjtye%40%3A
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Sydney%2C%20AU&destination=Perth%2C%20AU&waypoints=via%3Aenc%3AlexeF%7B~wsZejrPjtye%40%3A&key=YOUR_API_KEY'

يُرجى العِلم أنّه يمكنك المزج بحرية بين محدّد via: ومعدِّلات الموقع الجغرافي. على سبيل المثال:

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=Perth%2C%20AU
  &origin=Sydney%2C%20AU
  &waypoints=side_of_road%3Avia%3Aenc%3AlexeF%7B~wsZejrPjtye%40%3A
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Sydney%2C%20AU&destination=Perth%2C%20AU&waypoints=side_of_road%3Avia%3Aenc%3AlexeF%7B~wsZejrPjtye%40%3A&key=YOUR_API_KEY'

تحسين النقاط على المسار

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

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

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

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=Adelaide%2C%20SA
  &origin=Adelaide%2C%20SA
  &waypoints=optimize%3Atrue%7CBarossa%20Valley%2C%20SA%7CClare%2C%20SA%7CConnawarra%2C%20SA%7CMcLaren%20Vale%2C%20SA
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Adelaide%2C%20SA&destination=Adelaide%2C%20SA&waypoints=optimize%3Atrue%7CBarossa%20Valley%2C%20SA%7CClare%2C%20SA%7CConnawarra%2C%20SA%7CMcLaren%20Vale%2C%20SA&key=YOUR_API_KEY'

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

"waypoint_order": [ 3, 2, 0, 1 ]

القيود

يمكن احتساب الاتجاهات التي تلتزم بقيود معيّنة. يتم الإشارة إلى القيود باستخدام المَعلمة avoid، ووسيطة لهذه المَعلمة تشير إلى القيد الذي يجب تجنّبه. تتوفّر القيود التالية:

avoid=tolls
avoid=highways
avoid=ferries

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

ملاحظة: لا تمنع إضافة القيود المسارات التي تتضمّن الميزة المحظورة، بل تؤدي إلى تفضيل المسارات الأكثر ملاءمة.

أنظمة وحدات القياس

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

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

تحدّد السمة metric استخدام النظام المتري. يتم عرض المسافات النصية بالكيلومتر والمتر.
يحدّد imperial استخدام النظام الإمبراطوري (الإنجليزي). يتم عرض المسافات النصية باستخدام الأميال والأقدام.

ملاحظة: يؤثر إعداد نظام الوحدات هذا فقط في text المعروضة ضمن حقول distance. تحتوي حقول distance أيضًا على values التي يتم التعبير عنها دائمًا بالأمتار.

الانحياز إلى منطقة معيّنة

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

يمكنك استخدام أي نطاق أطلق فيه تطبيق "خرائط Google" الرئيسي اتجاهات القيادة.

على سبيل المثال، يؤدي طلب الاتجاهات من "Toledo" إلى "Madrid" إلى عرض نتائج مناسبة عند ضبط region على es، ويتم بعد ذلك تفسير "Toledo" على أنّها المدينة الإسبانية:

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=Madrid
  &origin=Toledo
  &region=es
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid®ion=es&key=YOUR_API_KEY'

JSON

      
{
  "geocoded_waypoints":
    [
      {
        "geocoder_status": "OK",
        "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y",
        "types": ["locality", "political"],
      },
      {
        "geocoder_status": "OK",
        "place_id": "ChIJgTwKgJcpQg0RaSKMYcHeNsQ",
        "types": ["locality", "political"],
      },
    ],
  "routes":
    [
      {
        "bounds":
          {
            "northeast": { "lat": 40.4165207, "lng": -3.7026134 },
            "southwest": { "lat": 39.862808, "lng": -4.029406799999999 },
          },
        "copyrights": "Map data ©2022 Inst. Geogr. Nacional",
        "legs":
          [
            {
              "distance": { "text": "74.3 km", "value": 74327 },
              "duration": { "text": "57 mins", "value": 3446 },
              "end_address": "Madrid, Spain",
              "end_location": { "lat": 40.4165207, "lng": -3.705076 },
              "start_address": "Toledo, Spain",
              "start_location": { "lat": 39.862808, "lng": -4.0273727 },
              "steps":
                [
                  {
                    "distance": { "text": "0.6 km", "value": 615 },
                    "duration": { "text": "2 mins", "value": 106 },
                    "end_location":
                      { "lat": 39.8681019, "lng": -4.029378299999999 },
                    "html_instructions": "Head <b>northwest</b> on <b>Av. de la Reconquista</b> toward <b>C. de la Diputación</b>",
                    "polyline":
                      {
                        "points": "quhrF`rqWCBQJUJm@PQFg@Ni@JeBh@}@XaD|@{@Vk@Ns@RUFoA^u@R_AXwA`@WHMBG@C?E?GAC?IC",
                      },
                    "start_location": { "lat": 39.862808, "lng": -4.0273727 },
                    "travel_mode": "DRIVING",
                  },
                  // Additional steps omitted for brevity
                ],
              "traffic_speed_entry": [],
              "via_waypoint": [],
            },
          ],
        "overview_polyline":
          {
            "points": "quhrF`rqWcHzBaNzDeG~A][?k@lA{Dr@mBR]HmA[WQDWE[g@mAeE... (truncated for brevity)",
          },
        "summary": "A-42",
        "warnings": [],
        "waypoint_order": [],
      },
    ],
  "status": "OK",
}

XML

      
<DirectionsResponse>
 <status>OK</status>
 <route>
  <summary>A-42</summary>
  <leg>
   <step>
    <travel_mode>DRIVING</travel_mode>
    <start_location>
     <lat>39.8628080</lat>
     <lng>-4.0273727</lng>
    </start_location>
    <end_location>
     <lat>39.8681019</lat>
     <lng>-4.0293783</lng>
    </end_location>
    <polyline>
     <points>quhrF`rqWCBQJUJm@PQFg@Ni@JeBh@}@XaD|@{@Vk@Ns@RUFoA^u@R_AXwA`@WHMBG@C?E?GAC?IC</points>
    </polyline>
    <duration>
     <value>106</value>
     <text>2 mins</text>
    </duration>
    <html_instructions>Head &lt;b&gt;northwest&lt;/b&gt; on &lt;b&gt;Av. de la Reconquista&lt;/b&gt; toward &lt;b&gt;C. de la Diputación&lt;/b&gt;</html_instructions>
    <distance>
     <value>615</value>
     <text>0.6 km</text>
    </distance>
   </step>
   <!-- Additional steps omitted for brevity -->
   <duration>
    <value>3446</value>
    <text>57 mins</text>
   </duration>
   <distance>
    <value>74327</value>
    <text>74.3 km</text>
   </distance>
   <start_location>
    <lat>39.8628080</lat>
    <lng>-4.0273727</lng>
   </start_location>
   <end_location>
    <lat>40.4165207</lat>
    <lng>-3.7050760</lng>
   </end_location>
   <start_address>Toledo, Spain</start_address>
   <end_address>Madrid, Spain</end_address>
  </leg>
  <copyrights>Map data ©2022 Inst. Geogr. Nacional</copyrights>
  <overview_polyline>
   <points>quhrF`rqWcHzBaNzDeG~A][?k@lA{Dr@mBR]HmA[WQDWE[g@mAeE... (truncated for brevity)</points>
  </overview_polyline>
  <bounds>
   <southwest>
    <lat>39.8628080</lat>
    <lng>-4.0294068</lng>
   </southwest>
   <northeast>
    <lat>40.4165207</lat>
    <lng>-3.7026134</lng>
   </northeast>
  </bounds>
 </route>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ8f21C60Lag0R_q11auhbf8Y</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJgTwKgJcpQg0RaSKMYcHeNsQ</place_id>
 </geocoded_waypoint>
</DirectionsResponse>

إذا أرسلت طلبًا للحصول على الاتجاهات من "طليطلة" إلى "مدريد" بدون المَعلمة region، لن تظهر أي نتائج لأنّ "طليطلة" تُفسَّر على أنّها المدينة في ولاية أوهايو وليس في إسبانيا:

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=Madrid
  &origin=Toledo
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&key=YOUR_API_KEY'

JSON

      
{
  "geocoded_waypoints":
    [
      {
        "geocoder_status": "OK",
        "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
        "types": ["locality", "political"],
      },
      {
        "geocoder_status": "OK",
        "place_id": "ChIJgTwKgJcpQg0RaSKMYcHeNsQ",
        "types": ["locality", "political"],
      },
    ],
  "routes": [],
  "status": "ZERO_RESULTS",
}

XML

      
<DirectionsResponse>
 <status>ZERO_RESULTS</status>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJeU4e_C2HO4gRRcM6RZ_IPHw</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJgTwKgJcpQg0RaSKMYcHeNsQ</place_id>
 </geocoded_waypoint>
</DirectionsResponse>

معدِّلات المواقع الجغرافية

يمكنك استخدام معدِّلات الموقع الجغرافي للإشارة إلى كيفية وصول السائقين إلى موقع جغرافي معيّن، وذلك باستخدام المَعلمة side_of_road لتحديد جانب الطريق الذي يجب استخدامه، أو من خلال تحديد عنوان للإشارة إلى الاتجاه الصحيح للسفر. يمكن دمج هذه المُعدِّلات بحرية مع المُعدِّل via: للنقاط على المسار المتوسطة.

تحديد أنّ المسارات يجب أن تمر عبر جانب معيّن من الطريق

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

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=side_of_road%3A37.7663444%2C-122.4412006
  &origin=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=37.7680296%2C-122.4375126&destination=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

عند استخدام side_of_road: مع خطوط متعدّدة مرمّزة، يتم تطبيق المَعلمة على كل موقع جغرافي على طول الخط المتعدّد.

لا يمكن استخدام المُعدِّل side_of_road: إلا مع القيود التالية:

إذا كانت مَعلمة وسيلة النقل mode هي driving أو لم يتم تحديدها (driving هي وسيلة النقل التلقائية)

تحديد أنّ المسارات يجب أن تتضمّن اتجاهًا معيّنًا

عند تحديد نقطة على المسار، يمكنك طلب أن يمرّ المسار عبر النقطة على المسار في اتجاه معيّن. يتم تحديد هذا الاتجاه باستخدام البادئة heading=X:، حيث يمثّل X قيمة عدد صحيح بالدرجات بين 0 (شاملة) و360 (غير شاملة). تشير القيمة 0 إلى الشمال، و90 إلى الشرق، مع الاستمرار في اتجاه عقارب الساعة. على سبيل المثال، في طلب الاتجاهات هذا، يتجه المسار شرقًا من نقطة الانطلاق، ثم ينعطف للخلف:

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=37.773245%2C-122.469502
  &origin=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=heading%3D90%3A37.773279%2C-122.468780&destination=37.773245%2C-122.469502&key=YOUR_API_KEY'

لا يمكن استخدام المُعدِّل heading=X: إلا مع القيود التالية:

مَعلمة السفر mode هي driving أو bicycling أو لم يتم تحديدها (driving هو وضع السفر التلقائي).
لم يتم تحديد المُعدِّل side_of_road للموقع الجغرافي نفسه.
يتم تحديد الموقع الجغرافي باستخدام قيمة خط العرض/خط الطول. لا يجوز لك استخدام heading مع العناوين أو أرقام تعريف الأماكن أو الخطوط المتعدّدة المرمّزة.

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

أمثلة على الطلبات

عنوان URL

curl

عنوان URL

curl

عنوان URL

curl

عنوان URL

curl

عنوان URL

curl

عنوان URL

curl

وسائل النقل

معلومات حركة المرور

عنوان URL

curl

نقاط الطريق

حدِّد المواقع الجغرافية في المَعلمة waypoints.

عنوان URL

curl

التأثير في المسارات من خلال نقاط التوقف ونقاط المرور

عنوان URL

curl

عنوان URL

curl

عنوان URL

curl

عنوان URL

curl

تحسين النقاط على المسار

عنوان URL

curl

القيود

أنظمة وحدات القياس

الانحياز إلى منطقة معيّنة

عنوان URL

curl

JSON

XML

عنوان URL

curl

JSON

XML

معدِّلات المواقع الجغرافية

تحديد أنّ المسارات يجب أن تمر عبر جانب معيّن من الطريق

عنوان URL

curl

تحديد أنّ المسارات يجب أن تتضمّن اتجاهًا معيّنًا

عنوان URL

curl

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

حدِّد المواقع الجغرافية في المَعلمة `waypoints`.