اختيار وسيلة نقل

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

استدعِ طريقة computeRoutes() لطلب مسار بين موقعَين جغرافيَّين. يوضّح المثال التالي كيفية تحديد طلب ثم استدعاء computeRoutes() للحصول على مسار. 

  // Import the Routes library.
  const { Route } = await google.maps.importLibrary('routes');

  // Define a computeRoutes request.
  const request = {
    origin: 'Mountain View, CA',
    destination: 'San Francisco, CA',
  };

  // Call the computeRoutes() method to get routes.
  const {routes} = await Route.computeRoutes(request);

اختيار الحقول المطلوب إرجاعها

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

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

حدِّد قائمة الحقول التي تحتاج إليها من خلال ضبط السمة ComputeRoutesRequest.fields، كما هو موضّح في المقتطف التالي: 

// Define a routes request.
const request = {
  origin: 'Mountain View, CA',
  destination: 'San Francisco, CA',
  fields: ['path'], // Request fields needed to draw polylines.
};

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

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

في ComputeRoutesRequest، يمكنك تحديد موقع جغرافي بأي من الطرق التالية:

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

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

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

تحديد الموقع الجغرافي كعنصر Place (الخيار المفضّل)

لتحديد موقع جغرافي باستخدام "مكان"، أنشئ مثيلاً جديدًا من Place. يعرض المقتطف التالي إنشاء مثيلات Place جديدة لكل من origin وdestination، ثم استخدامها في ComputeRoutesRequest: 

// Create a new Place for the origin.
const originPlace = new Place({
  id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
});

// Create a new Place for the destination.
const destinationPlace = new Place({
  id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
});

// Define a computeRoutes request.
const request = {
  origin: originPlace,
  destination: destinationPlace,
  fields: ['path'],
};

إحداثيات خطوط العرض/الطول

لتحديد موقع جغرافي كإحداثيات خطوط العرض/الطول، أنشئ مثيلاً جديدًا من google.maps.LatLngLiteral أو google.maps.LatLngAltitude أو google.maps.LatLngAltitudeLiteral. يعرض المقتطف التالي كيفية إنشاء مثيلات google.maps.LatLngLiteral جديدة لكل من origin وdestination، ثم استخدامها في computeRoutesRequest: 

// Create new LatLngLiteral objects for the origin and destination.
// Mountain View, CA
const originLatLng = {lat: 37.422000, lng: -122.084058};
// San Francisco, CA
const destinationLatLng = {lat: 37.774929, lng: -122.419415};

// Define a computeRoutes request.
const request = {
  origin: originLatLng,
  destination: destinationLatLng,
  fields: ['path'],
};

سلسلة العنوان

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

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

يعرض المقتطف التالي إنشاء ComputeRoutesRequest باستخدام سلسلة عناوين لـ origin وdestination: 

// Define a computeRoutes request.
const request = {
  origin: '1600 Amphitheatre Parkway, Mountain View, CA',
  destination: '345 Spear Street, San Francisco, CA',
  fields: ['path'],
};

تحديد المنطقة الخاصة بالعنوان

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

// Define a request with an incomplete address string.
const request = {
  origin: 'Toledo',
  destination: 'Madrid',
};

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

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

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

const request = {
  origin: 'Toledo',
  destination: 'Madrid',
  region: 'es', // Specify the region code for Spain.
};

رمز Plus Codes

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

رموز 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". بعد ذلك، يمكنك استخدام رمز الموقع المفتوح المكوّن من 10 أحرف بالكامل لتحديد قيمة الموقع الجغرافي على النحو التالي: "849VCWC8+R9".
  • يتألف الرمز المركّب من رمز محلي يتضمّن 6 أحرف أو أكثر، بالإضافة إلى موقع جغرافي واضح. على سبيل المثال، العنوان "450 Serra Mall, Stanford, CA 94305, USA" يتضمّن رمزًا محليًا هو "CRHJ+C3". بالنسبة إلى العنوان المركّب، ادمج الرمز المحلي مع جزء العنوان الذي يتضمّن المدينة والولاية والرمز البريدي والبلد بالشكل التالي: "CRHJ+C3 Stanford, CA 94305, USA".

يعرض المقتطف التالي كيفية احتساب مسار من خلال تحديد نقطة طريق لأصل المسار ووجهته باستخدام رموز Plus Codes: 

const request = {
  origin: '849VCWC8+R9', // Mountain View, CA
  destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
  fields: ['path'],
};