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

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

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

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

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

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

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

• قد يؤدي استخدام إحداثيات خطوط الطول/العرض إلى تحديد الموقع الجغرافي على الطريق الأقرب إلى هذه الإحداثيات، الأمر الذي قد لا يكون نقطة وصول إلى الموقع أو حتى طريق يؤدي إلى الوجهة بسرعة أو أمان.
• يجب أولاً ترميز سلاسل العناوين جغرافيًا باستخدام 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 A Amphitheatre Parkway, Mountain View, CA"). الترميز الجغرافي هو عملية تحويل سلسلة عناوين إلى إحداثيات خطوط العرض وخط الطول (مثل خط العرض 37.423021 وخط الطول -122.083739).

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

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

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

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

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

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

تحديد المنطقة التي يقع فيها العنوان

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

{
  "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",
      ...
    }
  ]
}

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

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

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

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

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

• يتألف الرمز العام من رمز منطقة مكوَّن من 4 أحرف ورمز محلي مكوَّن من 6 أحرف أو أكثر.

  على سبيل المثال، بالنسبة إلى العنوان "1600 Amphitheatre Parkway، Mountain View، كاليفورنيا"، الرمز العالمي هو "849V" والرمز المحلي هو "CWC8+R9". ويمكنك بعد ذلك استخدام رمز Plus Codes الكامل المكوّن من 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 Maps Platform، بما في ذلك Place Autocomplete و Place Details و Directions API و Geocoding API. على سبيل المثال، يمكنك استخدام Geocoding API لعكس ترميز الموقع الجغرافي لمكان معيّن محدّد بإحداثيات خطوط الطول والعرض لتحديد رمز Plus Code الخاص بالمكان.