ندعوك للانضمام إلينا في يوم منتدى مطوّري "منصة خرائط Google" القادم في سان فرانسيسكو في ديسمبر. قدِّم طلبك الآن لحضور الفعالية.

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

تحديد المواقع الجغرافية لمسار معيّن

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

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

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

تحديد المواقع الجغرافية لمسار

يمكنك تمثيل موقع جغرافي من خلال إنشاء عنصر Waypoint (REST) أو Waypoint (gRPC). في تعريف نقطة على المسار، يمكنك تحديد موقع جغرافي بأي من الطرق التالية:

رقم تعريف المكان (مفضّل)
إحداثيات خطوط العرض/الطول
سلسلة العنوان ("القاهرة، مصر" أو "الرياض، المملكة العربية السعودية")
Navigation point token
رمز Plus Codes

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

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

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

تحديد موقع جغرافي كرقم تعريف مكان

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

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

يستخدم المثال التالي السمة placeId لتمرير رقم تعريف مكان لكل من origin وdestination:

{
  "origin":{
    "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o"
  },
  "destination":{
    "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU"
  },
  ...
}

تحديد موقع جغرافي باستخدام إحداثيات خطوط العرض والطول

لتحديد الموقع الجغرافي في نقطة على المسار، حدِّد الموقع الجغرافي (REST) أو الموقع الجغرافي (gRPC) باستخدام إحداثيات خطوط العرض/الطول.

على سبيل المثال، حدِّد نقطة على المسار origin وdestination باستخدام الإحداثيات latitude وlongitude:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
...
}

تحديد موقع جغرافي كسلسلة عنوان

سلاسل العناوين هي عناوين حرفية تمثّلها سلسلة (مثل "1600 Amphitheatre Parkway, Mountain View, CA"). الترميز الجغرافي هو عملية تحويل سلسلة عنوان إلى إحداثيات خطوط العرض والطول (مثل خط العرض 37.423021 وخط الطول ‎-122.083739).

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

على سبيل المثال، لحساب مسار، يمكنك تحديد نقطة على المسار origin وdestination باستخدام سلاسل العناوين:

{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "450 Serra Mall, Stanford, CA 94305, USA"
  },
  ...
}

في هذا المثال، تستخدم Routes API الترميز الجغرافي لكلا العنوانَين من أجل تحويلهما إلى إحداثيات خطوط العرض والطول.

إذا كانت قيمة العنوان غامضة، قد تستدعي Routes API عملية بحث لإزالة الغموض عن العناوين المشابهة. على سبيل المثال، قد يكون "شارع 1" قيمة كاملة أو قيمة جزئية لـ "شارع 1 شمال شرق" أو "شارع 1 جنوب شرق". قد تختلف هذه النتيجة عن تلك التي تعرضها Geocoding API. يمكنك تجنُّب التفسيرات الخاطئة المحتملة باستخدام أرقام تعريف الأماكن.

ضبط المنطقة للعنوان

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

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE"
}

في هذا المثال، يتم تفسير "طليطلة" على أنّها مدينة في ولاية أوهايو في الولايات المتحدة، وليس في إسبانيا. وبالتالي، يعرض الطلب مصفوفة فارغة، ما يعني عدم توفّر أي مسارات:

{
  []
}

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

يؤدي طلب الاتجاهات من "طليطلة" إلى "مدريد" الذي يتضمّن المَعلمة regionCode إلى عرض نتائج مناسبة لأنّه يتم تفسير "طليطلة" على أنّها مدينة في إسبانيا:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE",
  "regionCode": "es"
}

يحتوي الردّ الآن على المسار المحسوب من توليدو في إسبانيا إلى مدريد في إسبانيا:

{
  "routes": [
    {
      "distanceMeters": 75330,
      "duration": "4137s",
      ...
    }
  ]
}

تحديد موقع جغرافي كرمز مميّز لنقطة التنقّل

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

يمكنك الحصول على رمز مميّز لنقطة التنقّل من خلال طلب طريقة "الوجهات" في Geocoding API.

لتحديد رمز مميّز لنقطة التنقّل:

احصل على navigationPointToken من طريقة SearchDestinations في Geocoding API. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات Geocoding API.
أنشئ نقطة على المسار من خلال تمرير navigationPointToken.

يستخدم المثال التالي السمة navigation_point_token لتمرير رمز مميّز لنقطة التنقّل لكل من origin وdestination:

{
  "origin":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_ORIGIN"
  },
  "destination":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_DESTINATION"
  },
  ...
}

تحديد موقع جغرافي كرمز Plus Code

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

تعمل رموز Plus Codes مثل عناوين الشوارع للأشخاص أو الأماكن التي ليس لها عنوان فعلي. بدلاً من العناوين التي تتضمّن أسماء الشوارع وأرقامها، تستند رموز Plus Codes إلى إحداثيات خطوط العرض والطول، ويتم عرضها كأرقام وأحرف.

طوّرت Google رموز Plus Codes لتوفير عناوين للجميع ولكل شيء. رمز Plus Code هو مرجع موقع جغرافي مشفّر، مشتق من إحداثيات خطوط العرض/الطول، ويمثّل منطقة: 1/8000 من الدرجة في 1/8000 من الدرجة (حوالي 14 مترًا × 14 مترًا عند خط الاستواء) أو أصغر. يمكنك استخدام Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها هذه العناوين أو التي لا تكون فيها المباني مرقّمة أو الشوارع مسماة.

يجب تنسيق رموز Plus Codes كرمز عالمي أو رمز مركّب:

يتألف الرمز العالمي من رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر.
على سبيل المثال، بالنسبة إلى العنوان "1600 Amphitheatre Parkway, Mountain View, CA"، يكون الرمز العالمي هو "849V" والرمز المحلي هو "CWC8+R9". بعد ذلك، يمكنك استخدام رمز Plus Code المكوّن من 10 أحرف بالكامل لتحديد قيمة الموقع الجغرافي على النحو التالي: "849VCWC8+R9".
يتألف الرمز المركّب من رمز محلي مكوّن من 6 أحرف أو أكثر، بالإضافة إلى موقع جغرافي واضح.
على سبيل المثال، العنوان "450 Serra Mall, Stanford, CA 94305, USA" له رمز محلي "CRHJ+C3". بالنسبة إلى العنوان المركّب، ادمج الرمز المحلي مع المدينة والولاية والرمز البريدي وجزء البلد من العنوان في النموذج "CRHJ+C3 Stanford, CA 94305, USA".

على سبيل المثال، يمكنك احتساب مسار من خلال تحديد نقطة على المسار origin وdestination باستخدام Plus Codes:
```
{
  "origin":{
    "address": "849VCWC8+R9"
  },
  "destination":{
    "address": "CRHJ+C3 Stanford, CA 94305, USA"
  },
  "travelMode": "DRIVE"
}
```

تتوفّر رموز Plus Codes في واجهات برمجة تطبيقات "منصة خرائط Google"، بما في ذلك الإكمال التلقائي (جديد) وتفاصيل المكان (جديد) وGeocoding API. على سبيل المثال، يمكنك استخدام Geocoding API لعكس الترميز الجغرافي لموقع جغرافي محدّد بإحداثيات خطوط العرض والطول من أجل تحديد رمز Plus Code الخاص بالموقع الجغرافي.