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

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

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

• تحديد وجهة المركبة وجانب الطريق
• تحديد نقاط المرور في منتصف الرحلة
• تحديد محطة توقّف على طول مسار
• ضبط نقطة ليمرّ بها مسار
• تحسين ترتيب محطات التوقف في مسار رحلتك

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

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

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

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

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

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

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

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

يمكنك الحصول على رمز مميّز لنقطة التنقّل من خلال استدعاء طريقة Destinations في Geocoding API.

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

1. احصل على navigationPointToken من طريقة SearchDestinations في Geocoding API. اطّلِع على مستندات Geocoding API للحصول على مزيد من المعلومات.
2. أنشئ نقطة طريق من خلال تمرير 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 Codes

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

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

طوّرت Google Plus Codes لتوفير مزايا العناوين للجميع. الرمز البريدي الإضافي هو مرجع مشفّر للموقع الجغرافي، مشتق من إحداثيات خطوط الطول والعرض، ويمثّل مساحة تبلغ 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 Code مع واجهات برمجة التطبيقات في منصة خرائط Google، بما في ذلك الإكمال التلقائي (جديد) وتفاصيل المكان (جديد) وGeocoding API. على سبيل المثال، يمكنك استخدام Geocoding API لإجراء عكس الترميز الجغرافي لموقع جغرافي محدّد بإحداثيات خطوط الطول والعرض لتحديد رمز Plus Codes الخاص بالموقع الجغرافي.