الحصول على مصفوفة مسار

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

إذا كان عنوان الفوترة الخاص بك يقع في المنطقة الاقتصادية الأوروبية، ستسري بنود خدمة "منصة خرائط Google" في المنطقة الاقتصادية الأوروبية على استخدامك للخدمات اعتبارًا من 8 تموز (يوليو) 2025. تختلف الوظائف حسب المنطقة. مزيد من المعلومات

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

الاطّلاع على رمز المصدر الكامل للمثال

يوضّح هذا المثال كيفية استخدام فئة "مصفوفة المسارات" لاحتساب المسافات والمُدد للتنقّل بين نقاط انطلاق ووجهات متعددة.

TypeScript

// Initialize and add the map.
let map;
let markers: google.maps.marker.AdvancedMarkerElement[] = [];
let center = { lat: 51.55, lng: -1.8 };

async function initMap(): Promise<void> {
  //  Request the needed libraries.
  //@ts-ignore
  const [{Map}, {Place}, {AdvancedMarkerElement, PinElement}, {RouteMatrix}] = await Promise.all([
    google.maps.importLibrary('maps') as Promise<google.maps.MapsLibrary>,
    google.maps.importLibrary('places') as Promise<google.maps.PlacesLibrary>,
    google.maps.importLibrary('marker') as Promise<google.maps.MarkerLibrary>,
    google.maps.importLibrary('routes') as Promise<google.maps.RoutesLibrary>
  ]);

  const bounds = new google.maps.LatLngBounds();

  map = new Map(document.getElementById('map') as HTMLElement, {
    zoom: 8,
    center: center,
    mapId: 'DEMO_MAP_ID',
  });

  // Build the request using Place instances.
  const origin1 = new Place({
    id: "ChIJ83WZp86p2EcRbMrkYqGncBQ", // Greenwich, London, UK
  });
  const origin2 = new Place({
    id: "ChIJCSkVvleJc0gR8HHaTGpajKc", // Southampton, UK
  });
  const destinationA = new Place({
    id: "ChIJYdizgWaDcUgRH9eaSy6y5I4", // Bristol, UK
  });
  const destinationB = new Place({
    id: "ChIJ9VPsNNQCbkgRDmeGZdsGNBQ", // Cardiff, UK
  });

  await Promise.all([
    origin1.fetchFields({ fields: ['location', 'displayName']}),
    origin2.fetchFields({ fields: ['location', 'displayName']}),
    destinationA.fetchFields({ fields: ['location', 'displayName']}),
    destinationB.fetchFields({ fields: ['location', 'displayName']}),
  ]);

  const request = {
    origins: [origin1, origin2], 
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    units: google.maps.UnitSystem.METRIC,
    fields: ['distanceMeters', 'durationMillis', 'condition'],
  };

  // Show the request.
  (document.getElementById("request") as HTMLDivElement).innerText =
    JSON.stringify(request, null, 2);

  // Get the RouteMatrix response.
  const response = await RouteMatrix.computeRouteMatrix(request); 

  // Show the response.
  (document.getElementById("response") as HTMLDivElement).innerText =
    JSON.stringify(response, null, 2);

  // Add markers for the origins.
  for (const origin of request.origins) {
    if (origin.location) {
      const pin = new PinElement({
        //@ts-ignore
        glyphText: "O",
        glyphColor: "white",
        background: "#137333",
        borderColor: "white",
      });
      const marker = new AdvancedMarkerElement({
        map,
        position: origin.location,
        content: pin.element,
        title: `Origin: ${origin.displayName}`,
      });
      markers.push(marker);
      bounds.extend(origin.location);
    }
  }

  // Add markers for the destinations.
  for (let i = 0; i < request.destinations.length; i++) {
    const destination = request.destinations[i];
    if (destination.location) {
      const pin = new PinElement({
        //@ts-ignore
        glyphText: "D",
        glyphColor: "white",
        background: "#C5221F",
        borderColor: "white",
      });

      const marker = new AdvancedMarkerElement({
        map,
        position: destination.location,
        content: pin.element,
        title: `Destination: ${destination.displayName}`,
      });

      markers.push(marker);
      bounds.extend(destination.location);
    }
  }

  // Fit the map to the bounds of all markers.
  map.fitBounds(bounds);
}

initMap();
index.ts

ملاحظة: يمكنك الاطّلاع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

// Initialize and add the map.
let map;
let markers = [];
let center = { lat: 51.55, lng: -1.8 };
async function initMap() {
    //  Request the needed libraries.
    //@ts-ignore
    const [{ Map }, { Place }, { AdvancedMarkerElement, PinElement }, { RouteMatrix }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('routes')
    ]);
    const bounds = new google.maps.LatLngBounds();
    map = new Map(document.getElementById('map'), {
        zoom: 8,
        center: center,
        mapId: 'DEMO_MAP_ID',
    });
    // Build the request using Place instances.
    const origin1 = new Place({
        id: "ChIJ83WZp86p2EcRbMrkYqGncBQ", // Greenwich, London, UK
    });
    const origin2 = new Place({
        id: "ChIJCSkVvleJc0gR8HHaTGpajKc", // Southampton, UK
    });
    const destinationA = new Place({
        id: "ChIJYdizgWaDcUgRH9eaSy6y5I4", // Bristol, UK
    });
    const destinationB = new Place({
        id: "ChIJ9VPsNNQCbkgRDmeGZdsGNBQ", // Cardiff, UK
    });
    await Promise.all([
        origin1.fetchFields({ fields: ['location', 'displayName'] }),
        origin2.fetchFields({ fields: ['location', 'displayName'] }),
        destinationA.fetchFields({ fields: ['location', 'displayName'] }),
        destinationB.fetchFields({ fields: ['location', 'displayName'] }),
    ]);
    const request = {
        origins: [origin1, origin2],
        destinations: [destinationA, destinationB],
        travelMode: 'DRIVING',
        units: google.maps.UnitSystem.METRIC,
        fields: ['distanceMeters', 'durationMillis', 'condition'],
    };
    // Show the request.
    document.getElementById("request").innerText =
        JSON.stringify(request, null, 2);
    // Get the RouteMatrix response.
    const response = await RouteMatrix.computeRouteMatrix(request);
    // Show the response.
    document.getElementById("response").innerText =
        JSON.stringify(response, null, 2);
    // Add markers for the origins.
    for (const origin of request.origins) {
        if (origin.location) {
            const pin = new PinElement({
                //@ts-ignore
                glyphText: "O",
                glyphColor: "white",
                background: "#137333",
                borderColor: "white",
            });
            const marker = new AdvancedMarkerElement({
                map,
                position: origin.location,
                content: pin.element,
                title: `Origin: ${origin.displayName}`,
            });
            markers.push(marker);
            bounds.extend(origin.location);
        }
    }
    // Add markers for the destinations.
    for (let i = 0; i < request.destinations.length; i++) {
        const destination = request.destinations[i];
        if (destination.location) {
            const pin = new PinElement({
                //@ts-ignore
                glyphText: "D",
                glyphColor: "white",
                background: "#C5221F",
                borderColor: "white",
            });
            const marker = new AdvancedMarkerElement({
                map,
                position: destination.location,
                content: pin.element,
                title: `Destination: ${destination.displayName}`,
            });
            markers.push(marker);
            bounds.extend(destination.location);
        }
    }
    // Fit the map to the bounds of all markers.
    map.fitBounds(bounds);
}
initMap();
index.js

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
/* Optional: Makes the sample page fill the window. */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

#container {
  height: 100%;
  display: flex;
}

#sidebar {
  flex-basis: 15rem;
  flex-grow: 1;
  padding: 1rem;
  max-width: 30rem;
  height: 100%;
  box-sizing: border-box;
  overflow: auto;
}

#map {
  flex-basis: 0;
  flex-grow: 4;
  height: 100%;
}

#sidebar {
  flex-direction: column;
}
style.css

HTML

<html>
  <head>
    <title>Route matrix</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="container">
      <div id="map"></div>
      <div id="sidebar">
        <h3 style="flex-grow: 0">Request</h3>
        <pre style="flex-grow: 1" id="request"></pre>
        <h3 style="flex-grow: 0">Response</h3>
        <pre style="flex-grow: 1" id="response"></pre>
      </div>
    </div>
    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "beta"});</script>
  </body>
</html>
index.html

تجربة عيّنة

JSFiddle.net

الحدود القصوى المسموح بها للطلبات

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

• لا يمكن أن يتجاوز عدد العناصر 625 للطرق التي ليست طرقًا من النوع TRANSIT.
• في حال تحديد TRANSITمسار، يجب ألا يتجاوز عدد العناصر 100.
• في حال تحديد TRAFFIC_AWARE_OPTIMAL، يجب ألا يتجاوز عدد العناصر 100.
• إذا حدّدت المصادر أو الوجهات باستخدام العناوين أو مثيلات المكان، يمكنك تحديد ما يصل إلى 50 إجماليًا بهذه الطريقة.

لمزيد من التفاصيل، يُرجى الاطّلاع على الحصول على مسار نقل عام.

مثال على طلب مصفوفة الطرق

يوضّح المثال التالي ComputeRouteMatrixRequest. يُجري هذا المثال ما يلي:

• تعرض هذه السمة كيفية تحديد مصفوفة من نقطتَي طريق للمصدر ونقطتَي طريق للوجهة. تحسب الطريقة مسارًا من كل نقطة بداية إلى كل وجهة، لذا يحتوي الرد على أربعة مسارات.
  في المصفوفة، يكون العنصر الأول في الفهرس 0، والعنصر الثاني في الفهرس 1، وهكذا.
• تحدّد هذه السمة الحقول المطلوب عرضها. في هذا المثال، تم ضبط الطلب لعرض durationMillis وdistanceMeters وcondition لكل مسار.

TypeScript

const request = {
  origins: [origin1, origin2], 
  destinations: [destinationA, destinationB],
  travelMode: 'DRIVING',
  units: google.maps.UnitSystem.METRIC,
  fields: ['distanceMeters', 'durationMillis', 'condition'],
};
index.ts

ملاحظة: يمكنك الاطّلاع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

const request = {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    units: google.maps.UnitSystem.METRIC,
    fields: ['distanceMeters', 'durationMillis', 'condition'],
};
index.js

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

"matrix": {
  "rows": [
    {
      "items": [
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 202587,
          "durationMillis": 10040000
        },
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 252734,
          "durationMillis": 12240000
        }
      ]
    },
    {
      "items": [
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 166135,
          "durationMillis": 6596000
        },
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 216282,
          "durationMillis": 8797000
        }
      ]
    }
  ]
}
    

حدِّد كل مسار في النتيجة باستخدام فهرسَي نقطة البداية ونقطة النهاية للعثور على RouteMatrixItem المقابل في المصفوفة الثنائية الأبعاد. على سبيل المثال، سيكون RouteMatrixItem الذي يصف المسار المحسوب من نقطة الأصل في الفهرس 1 ونقطة الوجهة 0 في الطلب في العنصر الثاني من مصفوفة RouteMatrix.rows والعنصر الأول من مصفوفة RouteMatrixRow.items.

يوضّح مقتطف الرمز التالي كيفية تحديد RouteMatrixItem للعثور على مسار من مصدر معيّن إلى وجهة معيّنة:

// Find the route for origin 'x' and destination 'y'.
const {matrix} = await RouteMatrix.computeRouteMatrix(request);
const myRouteMatrixItem = matrix.rows[x].items[y];
    

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

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

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

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

fields: ['durationMillis', 'distanceMeters', 'condition'],
    

تحديد حقول الإخفاء التي يجب استخدامها

في ما يلي كيفية تحديد الحقول التي تريد استخدامها وإنشاء أقنعة الحقول لها:

1. اطلب جميع الحقول باستخدام قناع الحقل ['*'].
   تنبيه: يمكنك استخدام قناع حقل حرف البدل هذا أثناء عملية التطوير لتحديد الحقول التي تحتاج إليها، ولكن لا تستخدمه في مرحلة الإنتاج. يؤدي طلب جميع الحقول في نتائج الإنتاج إلى ارتفاع التكاليف وزيادة أوقات الاستجابة. قد تزيد التكلفة أيضًا بشكل غير متوقّع عند إضافة ميزات أكثر تقدّمًا، لأنّ قناع الحقل هذا سيتضمّنها تلقائيًا. بدلاً من ذلك، اطلب الحقول التي تحتاجها فقط لتقليل التكاليف ووقت الاستجابة للطلبات.
2. اطّلِع على التسلسل الهرمي للحقول في الفئة RouteMatrixItem للحقول التي تريدها.

3. أنشئ أقنعة الحقول باستخدام التسلسل الهرمي للحقول المعروضة في الخطوة السابقة، وذلك باستخدام التنسيق التالي:

   topLevelField[.secondLevelField][.thirdLevelField][...]

على سبيل المثال، بالنسبة إلى RouteMatrixItem:

  "travelAdvisory": {
    "fuelConsumptionMicroliters": 0,
    "tollInfo": {
      "estimatedPrices": [
        {
          "currencyCode": "USD",
          "units": 4,
          "nanos": 400000000
        }
      ]
    }
  },
    

إذا كنت تريد عرض الحقل tollInfo فقط للسمة RouteMatrixItem، سيكون قناع الحقل على النحو التالي:

fields: ['travelAdvisory.tollInfo']

إذا كنت تريد بدلاً من ذلك طلب استهلاك الوقود المقدَّر، سيكون قناع الحقل على النحو التالي:

fields: ['travelAdvisory.fuelConsumptionMicroliters']

إذا أردت طلب كليهما، سيكون قناع الحقل على النحو التالي:

fields: ['travelAdvisory.fuelConsumptionMicroliters', 'travelAdvisory.tollInfo']

وإذا أردت طلب المجموعة الكاملة من إرشادات السفر، سيكون قناع الحقل على النحو التالي:

fields: ['travelAdvisory']

لا تتوفّر التسلسل الهرمي للمواقع إلا لمواقع RouteMatrix.computeRouteMatrix، ولا تتوفّر لمواقع Route.computeRoutes.

طلب مصفوفة مسارات النقل العام

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

• اضبط قيمة travelMode على TRANSIT.
• اطلب الحقل travelAdvisory.

مزيد من المعلومات حول مسارات النقل العام