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

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

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

أمثلة على الردود

يتم عرض ردود الاتجاهات بالتنسيق الذي يشير إليه العلامة output ضمن مسار طلب عنوان URL.

في ما يلي نموذج لطلب HTTP يحسب المسار من شيكاغو في إلينوي إلى لوس أنجلوس في كاليفورنيا عبر نقطتَين على المسار في جوبلين في ميزوري وأوكلاهوما سيتي في أوكلاهوما.

عنوان URL

https://maps.googleapis.com/maps/api/directions/json
  ?destination=Los%20Angeles%2C%20CA
  &origin=Chicago%2C%20IL
  &waypoints=Joplin%2C%20MO%7COklahoma%20City%2C%20OK
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/directions/json?origin=Chicago%2C%20IL&destination=Los%20Angeles%2C%20CA&waypoints=Joplin%2C%20MO%7COklahoma%20City%2C%20OK&key=YOUR_API_KEY'

يطلب المثال أعلاه ردًّا بتنسيق JSON. ويمكن أيضًا طلب ناتج XML. انقر على علامات التبويب أدناه للاطّلاع على نماذج ردود JSON وXML.

JSON

      
{
  "geocoded_waypoints":
    [
      {
        "geocoder_status": "OK",
        "place_id": "ChIJ7cv00DwsDogRAMDACa2m4K8",
        "types": ["locality", "political"],
      },
      {
        "geocoder_status": "OK",
        "place_id": "ChIJ69Pk6jdlyIcRDqM1KDY3Fpg",
        "types": ["locality", "political"],
      },
      {
        "geocoder_status": "OK",
        "place_id": "ChIJgdL4flSKrYcRnTpP0XQSojM",
        "types": ["locality", "political"],
      },
      {
        "geocoder_status": "OK",
        "place_id": "ChIJE9on3F3HwoAR9AhGJW_fL-I",
        "types": ["locality", "political"],
      },
    ],
  "routes":
    [
      {
        "bounds":
          {
            "northeast": { "lat": 41.8781139, "lng": -87.6297872 },
            "southwest": { "lat": 34.0523525, "lng": -118.2435717 },
          },
        "copyrights": "Map data ©2022 Google, INEGI",
        "legs":
          [
            {
              "distance": { "text": "579 mi", "value": 932311 },
              "duration": { "text": "8 hours 48 mins", "value": 31653 },
              "end_address": "Joplin, MO, USA",
              "end_location": { "lat": 37.0842449, "lng": -94.513284 },
              "start_address": "Chicago, IL, USA",
              "start_location": { "lat": 41.8781139, "lng": -87.6297872 },
              "steps":
                [
                  {
                    "distance": { "text": "443 ft", "value": 135 },
                    "duration": { "text": "1 min", "value": 24 },
                    "end_location": { "lat": 41.8769003, "lng": -87.6297353 },
                    "html_instructions": "Head <b>south</b> on <b>S Federal St</b> toward <b>W Van Buren St</b>",
                    "polyline": { "points": "eir~FdezuOdCEjBC" },
                    "start_location": { "lat": 41.8781139, "lng": -87.6297872 },
                    "travel_mode": "DRIVING",
                  },
                  {
                    "distance": { "text": "269 ft", "value": 82 },
                    "duration": { "text": "1 min", "value": 20 },
                    "end_location": { "lat": 41.8768866, "lng": -87.63073 },
                    "html_instructions": "Turn <b>right</b> at the 1st cross street onto <b>W Van Buren St</b>",
                    "maneuver": "turn-right",
                    "polyline": { "points": "sar~FzdzuO@fC?|@" },
                    "start_location": { "lat": 41.8769003, "lng": -87.6297353 },
                    "travel_mode": "DRIVING",
                  },
                  // Additional steps omitted for brevity
                ],
              "traffic_speed_entry": [],
              "via_waypoint": [],
            },
            // Additional legs (Joplin to Oklahoma City, Oklahoma City to Los Angeles) omitted for brevity
          ],
        "overview_polyline":
          {
            "points": "eir~FdezuOxyFzfFl`G|qZvtSzqo@d}EhlLtqIdjFhrTfvEdca@... (truncated for brevity)",
          },
        "summary": "I-55 S and I-44",
        "warnings": [],
        "waypoint_order": [0, 1],
      },
    ],
  "status": "OK",
}
      
      

XML

      
<DirectionsResponse>
 <status>OK</status>
 <route>
  <summary>I-55 S and I-44</summary>
  <leg>
   <step>
    <travel_mode>DRIVING</travel_mode>
    <start_location>
     <lat>41.8781139</lat>
     <lng>-87.6297872</lng>
    </start_location>
    <end_location>
     <lat>41.8769003</lat>
     <lng>-87.6297353</lng>
    </end_location>
    <polyline>
     <points>eir~FdezuOdCEjBC</points>
    </polyline>
    <duration>
     <value>24</value>
     <text>1 min</text>
    </duration>
    <html_instructions>Head &lt;b&gt;south&lt;/b&gt; on &lt;b&gt;S Federal St&lt;/b&gt; toward &lt;b&gt;W Van Buren St&lt;/b&gt;</html_instructions>
    <distance>
     <value>135</value>
     <text>443 ft</text>
    </distance>
   </step>
   <step>
    <travel_mode>DRIVING</travel_mode>
    <start_location>
     <lat>41.8769003</lat>
     <lng>-87.6297353</lng>
    </start_location>
    <end_location>
     <lat>41.8768866</lat>
     <lng>-87.6307300</lng>
    </end_location>
    <polyline>
     <points>sar~FzdzuO@fC?|@</points>
    </polyline>
    <duration>
     <value>20</value>
     <text>1 min</text>
    </duration>
    <html_instructions>Turn &lt;b&gt;right&lt;/b&gt; at the 1st cross street onto &lt;b&gt;W Van Buren St&lt;/b&gt;</html_instructions>
    <distance>
     <value>82</value>
     <text>269 ft</text>
    </distance>
    <maneuver>turn-right</maneuver>
   </step>
   <!-- Additional steps omitted for brevity -->
   <duration>
    <value>31653</value>
    <text>8 hours 48 mins</text>
   </duration>
   <distance>
    <value>932311</value>
    <text>579 mi</text>
   </distance>
   <start_location>
    <lat>41.8781139</lat>
    <lng>-87.6297872</lng>
   </start_location>
   <end_location>
    <lat>37.0842449</lat>
    <lng>-94.5132840</lng>
   </end_location>
   <start_address>Chicago, IL, USA</start_address>
   <end_address>Joplin, MO, USA</end_address>
  </leg>
  <!-- Additional legs (Joplin to Oklahoma City, Oklahoma City to Los Angeles) omitted for brevity -->
  <copyrights>Map data ©2022 Google, INEGI</copyrights>
  <overview_polyline>
   <points>eir~FdezuOxyFzfFl`G|qZvtSzqo@d}EhlLtqIdjFhrTfvEdca@... (truncated for brevity)</points>
  </overview_polyline>
  <waypoint_index>0</waypoint_index>
  <waypoint_index>1</waypoint_index>
  <bounds>
   <southwest>
    <lat>34.0523525</lat>
    <lng>-118.2435717</lng>
   </southwest>
   <northeast>
    <lat>41.8781139</lat>
    <lng>-87.6297872</lng>
   </northeast>
  </bounds>
 </route>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ7cv00DwsDogRAMDACa2m4K8</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ69Pk6jdlyIcRDqM1KDY3Fpg</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJgdL4flSKrYcRnTpP0XQSojM</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJE9on3F3HwoAR9AhGJW_fL-I</place_id>
 </geocoded_waypoint>
</DirectionsResponse>
      
      

سيستخدم الجزء المتبقي من هذه المستندات بنية JSON. في معظم الحالات، لا يهم تنسيق الإخراج لأغراض توضيح المفاهيم أو أسماء الحقول في المستندات. ومع ذلك، يُرجى مراعاة الاختلافات البسيطة التالية:

  • يتم تضمين نتائج XML في عنصر جذر <DirectionsResponse>.
  • يشير JSON إلى الإدخالات التي تحتوي على عناصر متعددة من خلال مصفوفات الجمع (مثل steps وlegs)، بينما يشير XML إليها باستخدام عناصر مفردة متعددة (مثل <step> و<leg>).
  • يشير JSON إلى ترتيب النقاط على المسار من خلال الحقل waypoint_order، بينما يشير XML إليها باستخدام عناصر <waypoint_index> فردية.
  • تتم الإشارة إلى العناصر الفارغة من خلال مصفوفات فارغة في JSON، ولكن من خلال عدم توفّر أي عنصر من هذا النوع في XML. على سبيل المثال، إذا لم يؤدّ الردّ إلى أي نتائج، سيتم عرض مصفوفة routes فارغة في JSON، ولكن لن يتم عرض أي عناصر <route> في XML.

DirectionsResponse

الحقل مطلوب النوع الوصف
مطلوب Array<DirectionsRoute>

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

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsRoute.

مطلوب DirectionsStatus

يحتوي على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تتبُّع سبب تعذُّر الطلب.

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsStatus.

اختياري Array<TravelMode>

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

لمزيد من المعلومات، يُرجى الاطّلاع على TravelMode.

اختياري سلسلة

عندما تعرض الخدمة رمز حالة غير OK، قد يكون هناك حقل error_message إضافي ضمن عنصر الاستجابة. يحتوي هذا الحقل على معلومات أكثر تفصيلاً عن الأسباب وراء رمز الحالة المحدّد. لا يتم عرض هذا الحقل دائمًا، ويخضع محتواه للتغيير.

اختياري Array<DirectionsGeocodedWaypoint>

يحتوي على مصفوفة تتضمّن تفاصيل حول الترميز الجغرافي لنقطة الانطلاق والوجهة والنقاط على المسار. تتوافق العناصر في مصفوفة geocoded_waypoints، حسب موضعها المستند إلى الصفر، مع نقطة الانطلاق ونقاط المسار بالترتيب المحدّد والوجهة.

لن تظهر هذه التفاصيل للنقاط على المسار المحدّدة كقيم نصية لخطوط العرض/الطول إذا لم تعرض الخدمة أي نتائج. ويرجع ذلك إلى أنّ هذه النقاط على المسار يتم عكس ترميزها الجغرافي فقط للحصول على عنوانها التمثيلي بعد العثور على مسار. سيشغل عنصر JSON فارغ الأماكن المقابلة في مصفوفة geocoded_waypoints.

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsGeocodedWaypoint.

DirectionsRoute

تتألف المسارات من legs وsteps متداخلَين.

الحقل مطلوب النوع الوصف
مطلوب الحدود

يحتوي على مربّع حدود إطار العرض لـ overview_polyline.

لمزيد من المعلومات، يُرجى الاطّلاع على الحدود.

مطلوب سلسلة

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

مطلوب صفيف<DirectionsLeg>

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

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsLeg.

مطلوب DirectionsPolyline

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

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsPolyline.

مطلوب سلسلة

يحتوي على وصف نصي قصير للمسار، وهو مناسب لتسمية المسار وتمييزه عن المسارات البديلة.

مطلوب Array<string>

تحتوي على مصفوفة من التحذيرات التي يتم عرضها عند عرض هذه الاتجاهات. ويجب التعامل مع هذه التحذيرات وعرضها بنفسك.

مطلوب Array<integer>

مصفوفة تشير إلى ترتيب أي نقاط على المسار في المسار المحسوب. قد تتم إعادة ترتيب هذه النقاط على المسار إذا تم تمرير الطلب optimize:true ضمن مَعلمة النقاط على المسار.

اختياري Fare

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

لمزيد من المعلومات، يُرجى الاطّلاع على الأجرة.

الحدود

مستطيل في الإحداثيات الجغرافية من النقاط في الزاويتين الجنوبية الغربية والشمالية الشرقية

الحقل مطلوب النوع الوصف
مطلوب LatLngLiteral لمزيد من المعلومات، يُرجى الاطّلاع على LatLngLiteral.
مطلوب LatLngLiteral لمزيد من المعلومات، يُرجى الاطّلاع على LatLngLiteral.

LatLngLiteral

عنصر يصف موقعًا جغرافيًا محدّدًا باستخدام خطوط العرض والطول بالدرجات العشرية

الحقل مطلوب النوع الوصف
مطلوب الرقم

خط العرض بالدرجات العشرية

مطلوب الرقم

خط الطول بالدرجات العشرية

DirectionsLeg

الحقل مطلوب النوع الوصف
مطلوب سلسلة

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

مطلوب LatLngLiteral

إحداثيات خط العرض/الطول للوجهة المحدّدة لهذا الجزء من الرحلة بما أنّ Directions API تحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب خيار نقل (عادةً طريق) عند نقطتَي البداية والنهاية، قد تختلف قيمة end_location عن الوجهة المقدَّمة لهذا الجزء من الرحلة إذا، على سبيل المثال، لم يكن هناك طريق بالقرب من الوجهة.

لمزيد من المعلومات، يُرجى الاطّلاع على LatLngLiteral.

مطلوب سلسلة

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

مطلوب LatLngLiteral

إحداثيات خط العرض/خط الطول لنقطة انطلاق هذا الجزء من الرحلة بما أنّ واجهة برمجة التطبيقات Directions API تحتسب الاتجاهات بين المواقع الجغرافية باستخدام أقرب خيار نقل (عادةً ما يكون طريقًا) في نقطتَي البداية والنهاية، قد تختلف قيمة start_location عن نقطة الانطلاق المقدَّمة لهذا الجزء من الرحلة إذا لم يكن هناك طريق بالقرب من نقطة الانطلاق مثلاً.

لمزيد من المعلومات، يُرجى الاطّلاع على LatLngLiteral.

مطلوب صفيف<DirectionsStep>

مصفوفة من الخطوات التي تشير إلى معلومات حول كل خطوة منفصلة من مرحلة الرحلة.

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsStep.

traffic_speed_entry

اختياري Array<DirectionsTrafficSpeedEntry>

معلومات عن سرعة حركة المرور على طول المرحلة

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsTrafficSpeedEntry.

مطلوب صفيف<DirectionsViaWaypoint>

المواقع الجغرافية للنقاط على المسار التي يمرّ بها هذا الجزء من الرحلة

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsViaWaypoint.

اختياري TimeZoneTextValueObject

يحتوي على الوقت المقدَّر للوصول إلى هذه المرحلة. لا يتم عرض هذه السمة إلا لاتجاهات النقل العام.

لمزيد من المعلومات، يُرجى الاطّلاع على TimeZoneTextValueObject.

اختياري TimeZoneTextValueObject

يحتوي على وقت المغادرة المقدَّر لهذه المرحلة، ويتم تحديده كعنصر Time. لا يتوفّر departure_time إلا لاتجاهات النقل العام.

لمزيد من المعلومات، يُرجى الاطّلاع على TimeZoneTextValueObject.

اختياري TextValueObject

إجمالي المسافة التي يغطيها هذا الجزء

لمزيد من المعلومات، يُرجى الاطّلاع على TextValueObject.

اختياري TextValueObject

إجمالي مدة هذا الجزء

لمزيد من المعلومات، يُرجى الاطّلاع على TextValueObject.

اختياري TextValueObject

تشير إلى المدة الإجمالية لهذا الجزء. هذه القيمة هي تقدير للوقت المستغرَق في حركة المرور استنادًا إلى أحوال حركة المرور الحالية والسابقة. اطّلِع على مَعلمة الطلب traffic_model للتعرّف على الخيارات التي يمكنك استخدامها لطلب أن تكون القيمة المعروضة متفائلة أو متشائمة أو أفضل تقدير. لا يتم عرض مدة الرحلة في حركة المرور إلا في حال استيفاء جميع الشروط التالية:

  • لا يتضمّن الطلب نقاط توقّف على المسار. إذا كان الطلب يتضمّن نقاطًا على المسار، يجب أن تبدأ بـ via: لتجنُّب التوقفات.
  • الطلب مخصّص لاتجاهات القيادة، ويتم ضبط مَعلمة mode على driving.
  • يتضمّن الطلب المَعلمة departure_time.
  • تتوفّر أحوال حركة المرور للمسار المطلوب.

لمزيد من المعلومات، يُرجى الاطّلاع على TextValueObject.

DirectionsStep

يحدّد كل عنصر في مصفوفة الخطوات خطوة واحدة من الاتجاهات المحسوبة. الخطوة هي الوحدة الأكثر دقة في مسار الاتجاه، وتحتوي على خطوة واحدة تصف تعليمات محدّدة واحدة حول الرحلة. مثلاً، "انعطِف يسارًا عند شارع W. 4th St." لا تصف الخطوة التعليمات فحسب، بل تحتوي أيضًا على معلومات المسافة والمدة المتعلقة بكيفية ارتباط هذه الخطوة بالخطوة التالية. على سبيل المثال، قد تحتوي الخطوة التي يُشار إليها باسم "الاندماج في الطريق السريع I-80 West" على مدة "37 ميلاً" و "40 دقيقة"، ما يشير إلى أنّ الخطوة التالية تبعد 37 ميلاً/40 دقيقة عن هذه الخطوة.

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

الحقل مطلوب النوع الوصف
مطلوب TextValueObject

يحتوي على الوقت المعتاد المطلوب لتنفيذ الخطوة، حتى الخطوة التالية. قد يكون هذا الحقل غير محدّد إذا كانت المدة غير معروفة.

لمزيد من المعلومات، يُرجى الاطّلاع على TextValueObject.

مطلوب LatLngLiteral

يحتوي على الموقع الجغرافي للنقطة الأخيرة في هذه الخطوة.

لمزيد من المعلومات، يُرجى الاطّلاع على LatLngLiteral.

مطلوب سلسلة

تحتوي على تعليمات منسَّقة لهذه الخطوة، ويتم عرضها كسلسلة نصية بتنسيق HTML. هذا المحتوى مخصّص للقراءة كما هو، لذا لا تحلّل هذا المحتوى المخصّص للعرض فقط بطريقة برمجية.

مطلوب DirectionsPolyline

يحتوي على عنصر نقاط واحد يتضمّن تمثيلاً للخطوط المتعدّدة المرمّزة للخطوة. هذا الشكل المتعدّد الخطوط هو مسار تقريبي (مبسّط) للخطوة.

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsPolyline.

مطلوب LatLngLiteral

يحتوي على الموقع الجغرافي لنقطة البداية لهذه الخطوة.

لمزيد من المعلومات، يُرجى الاطّلاع على LatLngLiteral.

مطلوب TravelMode

يحتوي على نوع وسيلة النقل المستخدَمة.

لمزيد من المعلومات، يُرجى الاطّلاع على TravelMode.

اختياري TextValueObject

يحتوي على المسافة التي تغطيها هذه الخطوة حتى الخطوة التالية. قد يكون هذا الحقل غير محدّد إذا كانت المسافة غير معروفة.

لمزيد من المعلومات، يُرجى الاطّلاع على TextValueObject.

اختياري سلسلة

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

The allowed values include: turn-slight-left, turn-sharp-left, turn-left, turn-slight-right, turn-sharp-right, keep-right, keep-left, uturn-left, uturn-right, turn-right, straight, ramp-left, ramp-right, merge, fork-left, fork-right, ferry, ferry-train, roundabout-left, and roundabout-right
اختياري

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

اختياري DirectionsTransitDetails

التفاصيل المتعلّقة بهذه الخطوة إذا كان وضع السفر هو transit.

لمزيد من المعلومات، يمكنك الاطّلاع على DirectionsTransitDetails.

TextValueObject

عنصر يحتوي على قيمة رقمية وتمثيل نصي منسَّق لها

الحقل مطلوب النوع الوصف
مطلوب سلسلة

قيمة السلسلة

مطلوب الرقم

تمثّل هذه السمة قيمة رقمية.

DirectionsPolyline

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

تحوّل عملية الترميز قيمة ثنائية إلى سلسلة من رموز الأحرف لأحرف ASCII باستخدام نظام ترميز base64 المألوف: لضمان عرض هذه الأحرف بشكل صحيح، يتم جمع القيم المرمّزة مع 63 (حرف ASCII "؟") قبل تحويلها إلى ASCII. تتحقّق الخوارزمية أيضًا من رموز الأحرف الإضافية لنقطة معيّنة من خلال التحقّق من البت الأقل أهمية لكل مجموعة بايت. إذا تم ضبط هذا البت على 1، يعني ذلك أنّ النقطة لم يتم تشكيلها بالكامل بعد ويجب أن تتبعها بيانات إضافية.

بالإضافة إلى ذلك، لتوفير المساحة، تتضمّن النقاط فقط الإزاحة من النقطة السابقة (باستثناء النقطة الأولى بالطبع). يتم ترميز جميع النقاط في Base64 كأعداد صحيحة موقَّعة، لأنّ خطوط العرض وخطوط الطول هي قيم موقَّعة. يجب أن يمثّل تنسيق الترميز ضمن الخطوط المتعدّدة إحداثيَين يمثّلان خط العرض وخط الطول بدقة معقولة. بافتراض أنّ الحد الأقصى لخط الطول هو +/- 180 درجة بدقة تصل إلى 5 منازل عشرية (من 180.00000 إلى ‎-180.00000)، يتطلب ذلك قيمة عدد صحيح ثنائي موقَّع من 32 بت.

الحقل مطلوب النوع الوصف
مطلوب سلسلة

تمثيل سلسلة واحدة للخطوط المتعدّدة

TravelMode

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

DirectionsTransitDetails

معلومات إضافية غير ذات صلة بوسائل النقل الأخرى

الحقل مطلوب النوع الوصف
اختياري DirectionsTransitStop

محطة الوصول لوسائل النقل العام

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsTransitStop.

اختياري TimeZoneTextValueObject لمزيد من المعلومات، يُرجى الاطّلاع على TimeZoneTextValueObject.
اختياري DirectionsTransitStop

محطة المغادرة في النقل العام

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsTransitStop.

اختياري TimeZoneTextValueObject لمزيد من المعلومات، يُرجى الاطّلاع على TimeZoneTextValueObject.
اختياري سلسلة

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

اختياري عدد صحيح

تحدّد عدد الثواني المتوقّع بين المغادرات من المحطة نفسها في هذا الوقت. على سبيل المثال، إذا كانت قيمة headway تساوي 600، من المتوقّع أن تنتظر عشر دقائق إذا فاتتك الحافلة.

اختياري DirectionsTransitLine

تحتوي على معلومات حول خط النقل العام المستخدَم في هذه الخطوة.

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsTransitLine.

اختياري عدد صحيح

عدد المحطات من محطة المغادرة إلى محطة الوصول ويشمل ذلك محطة الوصول، ولكن ليس محطة المغادرة. على سبيل المثال، إذا كانت الاتجاهات تتضمن المغادرة من المحطة "أ" والمرور بالمحطتين "ب" و"ج" والوصول إلى المحطة "د"، ستعرض السمة num_stops القيمة 3.

اختياري سلسلة

النص الذي يظهر في الجداول الزمنية ولوحات الإشارات لتحديد رحلة نقل عام للركاب يجب أن يحدّد النص رحلة بشكل فريد خلال يوم الخدمة. على سبيل المثال، "538" هو trip_short_name لقطار Amtrak الذي يغادر سان خوسيه، كاليفورنيا في الساعة 15:10 في أيام الأسبوع إلى ساكرامنتو، كاليفورنيا.

DirectionsTransitStop

الحقل مطلوب النوع الوصف
مطلوب LatLngLiteral

الموقع الجغرافي للمحطة

لمزيد من المعلومات، يُرجى الاطّلاع على LatLngLiteral.

مطلوب سلسلة

اسم محطة النقل العام

TimeZoneTextValueObject

عنصر يحتوي على وقت حقبة يونكس ومنطقة زمنية وتمثيل نصي منسَّق له.

الحقل مطلوب النوع الوصف
مطلوب سلسلة

الوقت المحدّد كسلسلة في المنطقة الزمنية

مطلوب سلسلة

يحتوي على المنطقة الزمنية. القيمة هي اسم المنطقة الزمنية كما هو محدّد في قاعدة بيانات المناطق الزمنية الصادرة عن هيئة أرقام الإنترنت المخصّصة (IANA)، مثل "America/New_York".

مطلوب الرقم

الوقت المحدّد كحقبة يونكس، أو الثواني منذ منتصف الليل، 1 يناير 1970 بالتوقيت العالمي المنسق.

DirectionsTransitLine

الحقل مطلوب النوع الوصف
مطلوب Array<DirectionsTransitAgency>

مؤسسات النقل العام التي تشغّل خط النقل العام هذا

لمزيد من المعلومات، يُرجى الاطّلاع على DirectionsTransitAgency.

مطلوب سلسلة

الاسم الكامل لخط النقل العام هذا، مثل "8 Avenue Local".

اختياري سلسلة

اللون المستخدَم عادةً في اللافتات لهذا الخط

اختياري سلسلة

تحتوي على عنوان URL للرمز المرتبط بهذا السطر.

اختياري سلسلة

الاسم المختصر لخط النقل العام هذا يكون هذا عادةً رقم خط، مثل "M7" أو "355".

اختياري سلسلة

اللون المستخدَم عادةً في اللافتات لهذا الخط

اختياري سلسلة

يحتوي على عنوان URL لخط النقل العام هذا كما قدّمته مؤسسة النقل العام.

اختياري DirectionsTransitVehicle

نوع المركبة التي تعمل على خط النقل العام هذا

لمزيد من المعلومات، يمكنك الاطّلاع على DirectionsTransitVehicle.

DirectionsTransitAgency

الحقل مطلوب النوع الوصف
اختياري سلسلة

اسم مؤسسة النقل العام هذه

اختياري سلسلة

رقم هاتف مؤسسة النقل العام

اختياري سلسلة

عنوان URL لمؤسسة النقل العام

DirectionsTransitVehicle

الحقل مطلوب النوع الوصف
مطلوب سلسلة

اسم هذه المركبة، مكتوبًا بأحرف كبيرة

مطلوب سلسلة

نوع المركبة المستخدَمة

  • ‫BUS - حافلة
  • CABLE_CAR - مركبة تعمل على كابل، عادةً على الأرض. قد تكون التلفريكات من النوع GONDOLA_LIFT.
  • ‫COMMUTER_TRAIN: قطار سريع
  • ‫FERRY - عبّارة
  • FUNICULAR: مركبة يتم سحبها إلى أعلى منحدر شديد بواسطة كابل. يتكوّن القطار المائل عادةً من عربتَين، وتعمل كل عربة كوزن موازن للأخرى.
  • ‫GONDOLA_LIFT: عربة تلفريك هوائية
  • ‫HEAVY_RAIL: سكك حديدية ثقيلة
  • ‫HIGH_SPEED_TRAIN: قطار فائق السرعة
  • ‫INTERCITY_BUS: حافلة بين المدن
  • ‫LONG_DISTANCE_TRAIN: قطار مسافات طويلة
  • ‫METRO_RAIL: قطار خفيف
  • ‫MONORAIL - قطار بخط حديدي واحد
  • ‫OTHER: سيتم عرض هذا النوع لجميع المركبات الأخرى.
  • RAIL - السكك الحديدية
  • SHARE_TAXI - سيارة الأجرة المشتركة هي نوع من الحافلات التي يمكنها إنزال الركاب وإقلالهم في أي مكان على طول مسارها.
  • ‫SUBWAY: قطار خفيف تحت الأرض
  • ‫TRAM: قطار خفيف فوق الأرض
  • ‫TROLLEYBUS - ترولي باص
The allowed values include: BUS, CABLE_CAR, COMMUTER_TRAIN, FERRY, FUNICULAR, GONDOLA_LIFT, HEAVY_RAIL, HIGH_SPEED_TRAIN, INTERCITY_BUS, LONG_DISTANCE_TRAIN, METRO_RAIL, MONORAIL, OTHER, RAIL, SHARE_TAXI, SUBWAY, TRAM, and TROLLEYBUS
اختياري سلسلة

تحتوي على عنوان URL لرمز مرتبط بنوع المركبة هذا.

اختياري سلسلة

يحتوي على عنوان URL للرمز المرتبط بنوع المركبة هذا، استنادًا إلى لافتات النقل المحلية.

DirectionsTrafficSpeedEntry

الحقل مطلوب النوع الوصف
مطلوب الرقم

تمثّل هذه السمة الإزاحة على طول المسار (بالأمتار) التي تكون فئة السرعة هذه صالحة لها.

مطلوب سلسلة

حالة حركة المرور/السرعة الحالية في هذا الجزء من المسار

DirectionsViaWaypoint

الحقل مطلوب النوع الوصف
اختياري LatLngLiteral

الموقع الجغرافي للنقطة على المسار

لمزيد من المعلومات، يُرجى الاطّلاع على LatLngLiteral.

اختياري عدد صحيح

فهرس الخطوة التي تحتوي على النقطة على المسار

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

موضع النقطة على المسار على طول الخطوط المتعدّدة للخطوة، ويتم التعبير عنه كنسبة من 0 إلى 1.

السعر

إجمالي الأجرة للمسار

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}
الحقل مطلوب النوع الوصف
مطلوب سلسلة

رمز العملة ISO 4217 الذي يشير إلى العملة التي يتم التعبير عن المبلغ بها

مطلوب سلسلة

إجمالي مبلغ الأجرة، منسَّق باللغة المطلوبة

مطلوب الرقم

إجمالي مبلغ الأجرة بالعملة المحدّدة

DirectionsStatus

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

  • تشير القيمة OK إلى أنّ الردّ يحتوي على نتيجة صالحة.
  • تشير السمة NOT_FOUND إلى أنّه تعذّر ترميز موقع جغرافي واحد على الأقل من المواقع الجغرافية المحدّدة في نقطة الانطلاق أو الوجهة أو النقاط على المسار في الطلب.
  • تشير السمة ZERO_RESULTS إلى أنّه تعذّر العثور على مسار بين نقطة الانطلاق والوجهة.
  • تشير السمة MAX_WAYPOINTS_EXCEEDED إلى أنّه تم تقديم عدد كبير جدًا من النقاط على المسار في الطلب. بالنسبة إلى التطبيقات التي تستخدم Directions API كخدمة ويب أو خدمة الاتجاهات في Maps JavaScript API، يبلغ الحد الأقصى المسموح به لعدد النقاط على المسار 25 نقطة، بالإضافة إلى نقطة الانطلاق والوجهة.
  • تشير السمة MAX_ROUTE_LENGTH_EXCEEDED إلى أنّ المسار المطلوب طويل جدًا ولا يمكن معالجته. يحدث هذا الخطأ عند عرض اتجاهات أكثر تعقيدًا. يُرجى محاولة تقليل عدد النقاط على المسار أو المنعطفات أو التعليمات.
  • تشير السمة INVALID_REQUEST إلى أنّ الطلب المقدَّم غير صالح. وتشمل الأسباب الشائعة لهذه الحالة معلَمة أو قيمة معلَمة غير صالحة.
  • تشير السمة OVER_DAILY_LIMIT إلى أيّ مما يلي:
    • مفتاح واجهة برمجة التطبيقات غير متوفّر أو غير صالح.
    • لم يتم تفعيل الفوترة في حسابك.
    • تم تجاوز الحد الأقصى للاستخدام الذي فرضته على نفسك.
    • لم تعُد طريقة الدفع المقدَّمة صالحة (على سبيل المثال، انتهت صلاحية بطاقة الائتمان).
    يمكنك الاطّلاع على الأسئلة الشائعة حول "خرائط Google" لمعرفة كيفية حلّ هذه المشكلة.
  • يشير الرمز OVER_QUERY_LIMIT إلى أنّ الخدمة قد تلقّت عددًا كبيرًا جدًا من الطلبات من تطبيقك خلال الفترة الزمنية المسموح بها.
  • REQUEST_DENIED تشير إلى أنّ الخدمة رفضت استخدام تطبيقك لخدمة الاتجاهات.
  • تشير السمة UNKNOWN_ERROR إلى أنّه تعذّرت معالجة طلب الاتجاهات بسبب خطأ في الخادم. قد ينجح الطلب إذا أعدت المحاولة.

DirectionsGeocodedWaypoint

الحقل مطلوب النوع الوصف
اختياري سلسلة

يشير إلى رمز الحالة الناتج عن عملية الترميز الجغرافي. قد يحتوي هذا الحقل على القيم التالية.

The allowed values include: OK, and ZERO_RESULTS
اختياري

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

تحدث المطابقات الجزئية في أغلب الأحيان لعناوين الشوارع غير الموجودة ضمن المنطقة التي تم تمريرها في الطلب. قد يتم أيضًا عرض المطابقات الجزئية عندما يتطابق طلب مع موقعَين جغرافيَين أو أكثر في المنطقة نفسها. على سبيل المثال، سيؤدي البحث عن "‎21 Henr St, Bristol, UK" إلى عرض مطابقة جزئية لكل من Henry Street وHenrietta Street. يُرجى العِلم أنّه إذا تضمّن الطلب مكوّن عنوان يحتوي على أخطاء إملائية، قد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. وسيتم أيضًا وضع علامة على الاقتراحات التي يتم عرضها بهذه الطريقة على أنّها مطابقة جزئية.

اختياري سلسلة

معرّف فريد يمكن استخدامه مع Google APIs الأخرى اطّلِع على نظرة عامة على رقم تعريف المكان.

اختياري Array<string>

يشير إلى نوع العنوان لنتيجة الترميز الجغرافي المستخدَمة لحساب الاتجاهات.

  • administrative_area_level_1 تشير إلى منطقة إدارية من الدرجة الأولى تندرج تحت مستوى البلد. في الولايات المتحدة، هذه المستويات الإدارية هي الولايات. لا تستخدم بعض البلدان هذه المستويات الإدارية. في معظم الحالات، ستتطابق الأسماء المختصرة لـ administrative_area_level_1 بشكل وثيق مع التقسيمات الفرعية لمعيار ISO 3166-2 والقوائم الأخرى التي يتم تداولها على نطاق واسع، ولكن هذا غير مضمون لأنّ نتائج الترميز الجغرافي تستند إلى مجموعة متنوعة من الإشارات وبيانات الموقع الجغرافي.
  • يشير الرمز administrative_area_level_2 إلى منطقة إدارية من الدرجة الثانية تندرج تحت مستوى البلد. في الولايات المتحدة، تكون هذه المستويات الإدارية هي المقاطعات. لا تستخدم بعض البلدان هذه المستويات الإدارية.
  • يشير الرمز administrative_area_level_3 إلى منطقة إدارية من الدرجة الثالثة تندرج تحت مستوى البلد. يشير هذا النوع إلى قسم مدني فرعي. لا تستخدم بعض البلدان هذه المستويات الإدارية.
  • administrative_area_level_4 يشير إلى منطقة إدارية من الدرجة الرابعة تندرج تحت مستوى البلد. يشير هذا النوع إلى قسم مدني فرعي. لا تستخدم بعض البلدان هذه المستويات الإدارية.
  • يشير الرمز administrative_area_level_5 إلى منطقة إدارية من الدرجة الخامسة تندرج تحت مستوى البلد. يشير هذا النوع إلى قسم مدني فرعي. لا تستخدم بعض البلدان هذه المستويات الإدارية.
  • يشير الرمز airport إلى مطار.
  • تشير السمة colloquial_area إلى اسم بديل شائع الاستخدام للجهة.
  • تشير السمة country إلى الكيان السياسي الوطني، وهي عادةً أعلى نوع ترتيب تعرضه أداة الترميز الجغرافي.
  • يشير الرمز intersection إلى تقاطع رئيسي، عادةً ما يكون بين طريقَين رئيسيَين.
  • تشير السمة locality إلى كيان سياسي لمدينة أو بلدة مدمجة.
  • يشير الرمز natural_feature إلى معلم طبيعي بارز.
  • تشير السمة neighborhood إلى حيّ مُسمّى
  • تشير العلامة park إلى متنزّه يحمل اسمًا.
  • تشير السمة plus_code إلى مرجع موقع جغرافي مرمّز، مشتق من خط العرض وخط الطول. يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها هذه العناوين (حيث لا يتم ترقيم المباني أو تسمية الشوارع). لمزيد من التفاصيل، يُرجى الانتقال إلى https://plus.codes.
  • يشير الرمز point_of_interest إلى نقطة اهتمام مُسمّاة. عادةً ما تكون "نقاط الاهتمام" هذه كيانات محلية بارزة لا تندرج بسهولة ضمن فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".
  • تشير السمة political إلى جهة سياسية. يشير هذا النوع عادةً إلى مضلّع لإدارة مدنية معيّنة.
  • تشير السمة postal_code إلى رمز بريدي يُستخدَم لإرسال البريد العادي داخل البلد.
  • premise تشير إلى موقع جغرافي مسمّى، وعادةً ما يكون مبنى أو مجموعة من المباني التي تحمل اسمًا شائعًا
  • تشير السمة route إلى مسار مسمّى (مثل "US 101").
  • تشير السمة street_address إلى عنوان شارع دقيق.
  • يشير الرمز sublocality إلى كيان مدني من الدرجة الأولى تحت مستوى منطقة محلية. بالنسبة إلى بعض المواقع الجغرافية، قد يتم تلقّي أحد الأنواع الإضافية: sublocality_level_1 إلى sublocality_level_5. وكل مستوى من مستويات الموقع الجغرافي الفرعي هو كيان مدني. وتشير الأرقام الأكبر إلى منطقة جغرافية أصغر.
  • تشير السمة subpremise إلى كيان من الدرجة الأولى تحت موقع جغرافي مسمّى، ويكون عادةً مبنى واحدًا ضمن مجموعة من المباني التي تحمل اسمًا مشتركًا
  • يشير الرمز tourist_attraction إلى مَعلم سياحي.
  • يشير الرمز train_station إلى محطة قطار.
  • يشير الرمز transit_station إلى محطة نقل عام.

تشير قائمة الأنواع الفارغة إلى عدم توفّر أنواع معروفة لمكوّن العنوان المحدّد، مثل Lieu-dit في فرنسا.