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

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

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

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

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

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

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

  • يمكن أن يؤدي استخدام إحداثيات خطوط الطول والعرض إلى تثبيت الموقع الجغرافي على الطريق الأقرب إلى تلك الإحداثيات، والتي قد لا تكون نقطة وصول إلى الموقع، أو حتى طريق تؤدي إلى الوجهة بسرعة أو بأمان.
  • يجب أولاً ترميز سلاسل العناوين جغرافيًا باستخدام 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 عملية بحث لتحديد الفرق بين العنوان والقيم المشابهة له. على سبيل المثال، يمكن أن تكون "الشارع الأول" قيمة كاملة أو قيمة جزئية لسمة "الشارع الأول شمال شرق" أو "الشارع الأول جنوب شرق". قد تختلف هذه النتيجة عن النتيجة التي تعرضها واجهة برمجة التطبيقات Geocoding API. يمكنك تجنُّب التفسيرات الخاطئة المحتمَلة باستخدام معرّفات الأماكن.

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

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

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

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

{
  []
}

يمكنك ضبط واجهة برمجة التطبيقات لعرض نتائج متحيّزة لمنطقة معيّنة من خلال تضمين المَعلمة regionCode. تحدّد هذه المَعلمة رمز المنطقة على أنّه قيمة مكوّنة من حرفَين لنطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD). تتطابق معظم رموز نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد مع رموز ISO 3166-1، مع اختلافات قليلة مهمة. على سبيل المثال، رمز المستوى الأعلى للمنطقة المحدودة (ccTLD) في المملكة المتحدة هو "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 لتوفير ميزة العناوين للجميع والأماكن. رمز الموقع المفتوح هو مرجع موقع جغرافي مشفَّر، يتم الحصول عليه من إحداثيات خطوط الطول والعرض، ويمثّل منطقة: 1/8000 من الدرجة في 1/8000 من الدرجة (حوالي 14 مترًا في 14 مترًا عند خط الاستواء) أو أصغر. يمكنك استخدام Plus Codes كبديل لعناوين الشارع في الأماكن التي لا تتوفّر فيها هذه العناوين أو التي لا يتم فيها ترقيم المباني أو تسمية الشوارع.

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

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

    على سبيل المثال، بالنسبة إلى العنوان "1600 Amphitheatre Parkway، Mountain View، كاليفورنيا"، الرمز العالمي هو "849V" والرمز المحلي هو "CWC8+R9". بعد ذلك، استخدِم رمز الموقع المفتوح الكامل المكوّن من 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 الخاص بالمكان.