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

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

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

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

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

يوضّح نموذج الرمز التالي كيفية الحصول على مسار لتعليمات القيادة بين موقعَين جغرافيَّين.

TypeScript

// Initialize and add the map.
let map: google.maps.Map;
let mapPolylines: google.maps.Polyline[] = [];
const center = { lat: 37.447646, lng: -122.113878 }; // Palo Alto, CA

// Initialize and add the map.
async function init(): Promise<void> {
    //  Request the needed libraries.
    const [{ Map }, { Place }, { Route }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
        google.maps.importLibrary('routes'),
    ]);

    map = new Map(document.getElementById('map')!, {
        zoom: 12,
        center,
        mapTypeControl: false,
        mapId: 'DEMO_MAP_ID',
    });

    // Use address strings in a directions request.
    const requestWithAddressStrings = {
        origin: '1600 Amphitheatre Parkway, Mountain View, CA',
        destination: '345 Spear Street, San Francisco, CA',
        fields: ['path'],
    };
    console.log({ requestWithAddressStrings });

    // Use Place IDs in a directions request.
    const originPlaceInstance = new Place({
        id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
    });

    const destinationPlaceInstance = new Place({
        id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
    });

    const requestWithPlaceIds: google.maps.routes.ComputeRoutesRequest = {
        origin: originPlaceInstance,
        destination: destinationPlaceInstance,
        fields: ['path'], // Request fields needed to draw polylines.
    };
    console.log({ requestWithPlaceIds });

    // Use lat/lng in a directions request.
    // Mountain View, CA
    const originLatLng = { lat: 37.422, lng: -122.084058 };
    // San Francisco, CA
    const destinationLatLng = { lat: 37.774929, lng: -122.419415 };

    // Define a computeRoutes request.
    const requestWithLatLngs: google.maps.routes.ComputeRoutesRequest = {
        origin: originLatLng,
        destination: destinationLatLng,
        fields: ['path'],
    };
    console.log({ requestWithLatLngs });

    // Use Plus Codes in a directions request.
    const requestWithPlusCodes: google.maps.routes.ComputeRoutesRequest = {
        origin: '849VCWC8+R9', // Mountain View, CA
        destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
        fields: ['path'],
    };
    console.log({ requestWithPlusCodes });

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

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

    // Use createPolylines to create polylines for the route.
    if (!routes) {
        console.warn('No routes found.');
        return;
    }
    mapPolylines = routes[0].createPolylines();
    // Add polylines to the map.
    mapPolylines.forEach((polyline) => {
        polyline.setMap(map);
    });

    // Create markers to start and end points.
    const markers = await routes[0].createWaypointAdvancedMarkers();
    // Add markers to the map
    markers.forEach((marker) => {
        marker.map = map;
    });

    // Display the raw JSON for the result in the console.
    console.log(`Response:\n ${JSON.stringify(routes, null, 2)}`);

    // Fit the map to the path.
    void fitMapToPath(routes[0].path!);
}

// Helper function to fit the map to the path.
async function fitMapToPath(path: google.maps.LatLngLiteral[]) {
    const { LatLngBounds } = await google.maps.importLibrary('core');
    const bounds = new LatLngBounds();
    path.forEach((point) => {
        bounds.extend(point);
    });
    map.fitBounds(bounds);
}

void init();
index.ts

ملاحظة: يُرجى قراءة دليل استخدام TypeScript و"خرائط Google".

JavaScript

// Initialize and add the map.
let map;
let mapPolylines = [];
const center = { lat: 37.447646, lng: -122.113878 }; // Palo Alto, CA

// Initialize and add the map.
async function init() {
    //  Request the needed libraries.
    const [{ Map }, { Place }, { Route }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
        google.maps.importLibrary('routes'),
    ]);

    map = new Map(document.getElementById('map'), {
        zoom: 12,
        center,
        mapTypeControl: false,
        mapId: 'DEMO_MAP_ID',
    });

    // Use address strings in a directions request.
    const requestWithAddressStrings = {
        origin: '1600 Amphitheatre Parkway, Mountain View, CA',
        destination: '345 Spear Street, San Francisco, CA',
        fields: ['path'],
    };
    console.log({ requestWithAddressStrings });

    // Use Place IDs in a directions request.
    const originPlaceInstance = new Place({
        id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
    });

    const destinationPlaceInstance = new Place({
        id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
    });

    const requestWithPlaceIds = {
        origin: originPlaceInstance,
        destination: destinationPlaceInstance,
        fields: ['path'], // Request fields needed to draw polylines.
    };
    console.log({ requestWithPlaceIds });

    // Use lat/lng in a directions request.
    // Mountain View, CA
    const originLatLng = { lat: 37.422, lng: -122.084058 };
    // San Francisco, CA
    const destinationLatLng = { lat: 37.774929, lng: -122.419415 };

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

    // Use Plus Codes in a directions request.
    const requestWithPlusCodes = {
        origin: '849VCWC8+R9', // Mountain View, CA
        destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
        fields: ['path'],
    };
    console.log({ requestWithPlusCodes });

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

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

    // Use createPolylines to create polylines for the route.
    if (!routes) {
        console.warn('No routes found.');
        return;
    }
    mapPolylines = routes[0].createPolylines();
    // Add polylines to the map.
    mapPolylines.forEach((polyline) => {
        polyline.setMap(map);
    });

    // Create markers to start and end points.
    const markers = await routes[0].createWaypointAdvancedMarkers();
    // Add markers to the map
    markers.forEach((marker) => {
        marker.map = map;
    });

    // Display the raw JSON for the result in the console.
    console.log(`Response:\n ${JSON.stringify(routes, null, 2)}`);

    // Fit the map to the path.
    void fitMapToPath(routes[0].path);
}

// Helper function to fit the map to the path.
async function fitMapToPath(path) {
    const { LatLngBounds } = await google.maps.importLibrary('core');
    const bounds = new LatLngBounds();
    path.forEach((point) => {
        bounds.extend(point);
    });
    map.fitBounds(bounds);
}

void init();
index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
#map {
    height: 100%;
}

/*
   * Optional: Makes the sample page fill the window.
   */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}
style.css

HTML

<html>
    <head>
        <title>Get directions</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <div id="map"></div>
    </body>
</html>
index.html

يمكنك استدعاء طريقة 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);
    

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

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

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

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

TypeScript

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

ملاحظة: يُرجى قراءة دليل استخدام TypeScript و"خرائط Google".

JavaScript

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

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

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

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

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

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

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

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

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

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

TypeScript

// Use Place IDs in a directions request.
const originPlaceInstance = new Place({
    id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
});

const destinationPlaceInstance = new Place({
    id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
});

const requestWithPlaceIds: google.maps.routes.ComputeRoutesRequest = {
    origin: originPlaceInstance,
    destination: destinationPlaceInstance,
    fields: ['path'], // Request fields needed to draw polylines.
};
index.ts

ملاحظة: يُرجى قراءة دليل استخدام TypeScript و"خرائط Google".

JavaScript

// Use Place IDs in a directions request.
const originPlaceInstance = new Place({
    id: 'ChIJiQHsW0m3j4ARm69rRkrUF3w', // Mountain View, CA
});

const destinationPlaceInstance = new Place({
    id: 'ChIJIQBpAG2ahYAR_6128GcTUEo', // San Francisco, CA
});

const requestWithPlaceIds = {
    origin: originPlaceInstance,
    destination: destinationPlaceInstance,
    fields: ['path'], // Request fields needed to draw polylines.
};
index.js

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

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

TypeScript

// Use lat/lng in a directions request.
// Mountain View, CA
const originLatLng = { lat: 37.422, lng: -122.084058 };
// San Francisco, CA
const destinationLatLng = { lat: 37.774929, lng: -122.419415 };

// Define a computeRoutes request.
const requestWithLatLngs: google.maps.routes.ComputeRoutesRequest = {
    origin: originLatLng,
    destination: destinationLatLng,
    fields: ['path'],
};
index.ts

ملاحظة: يُرجى قراءة دليل استخدام TypeScript و"خرائط Google".

JavaScript

// Use lat/lng in a directions request.
// Mountain View, CA
const originLatLng = { lat: 37.422, lng: -122.084058 };
// San Francisco, CA
const destinationLatLng = { lat: 37.774929, lng: -122.419415 };

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

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

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

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

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

TypeScript

// Use address strings in a directions request.
const requestWithAddressStrings = {
    origin: '1600 Amphitheatre Parkway, Mountain View, CA',
    destination: '345 Spear Street, San Francisco, CA',
    fields: ['path'],
};
index.ts

ملاحظة: يُرجى قراءة دليل استخدام TypeScript و"خرائط Google".

JavaScript

// Use address strings in a directions request.
const requestWithAddressStrings = {
    origin: '1600 Amphitheatre Parkway, Mountain View, CA',
    destination: '345 Spear Street, San Francisco, CA',
    fields: ['path'],
};
index.js

ضبط المنطقة للعنوان

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

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

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

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

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

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

• الرمز العالمي يتألف من رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر على سبيل المثال، بالنسبة إلى العنوان "1600 Amphitheatre Parkway, Mountain View, CA"، يكون الرمز العالمي هو "849V" والرمز المحلي هو "CWC8+R9". بعد ذلك، يمكنك استخدام رمز Plus Codes الكامل المكوّن من 10 أحرف لتحديد قيمة الموقع الجغرافي على النحو التالي: "849VCWC8+R9".
• الرمز المركّب يتألف من رمز محلي مكوّن من 6 أحرف أو أكثر مدمج مع موقع جغرافي صريح. على سبيل المثال، العنوان "450 Serra Mall, Stanford, CA 94305, USA" له رمز محلي هو "CRHJ+C3". بالنسبة إلى العنوان المركّب، ادمِج الرمز المحلي مع المدينة، الولاية والرمز البريدي والبلد من العنوان بالتنسيق "CRHJ+C3 Stanford, CA 94305, USA".

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

TypeScript

// Use Plus Codes in a directions request.
const requestWithPlusCodes: google.maps.routes.ComputeRoutesRequest = {
    origin: '849VCWC8+R9', // Mountain View, CA
    destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
    fields: ['path'],
};
index.ts

ملاحظة: يُرجى قراءة دليل استخدام TypeScript و"خرائط Google".

JavaScript

// Use Plus Codes in a directions request.
const requestWithPlusCodes = {
    origin: '849VCWC8+R9', // Mountain View, CA
    destination: 'CRHJ+C3 Stanford, CA 94305, USA', // Stanford, CA
    fields: ['path'],
};
index.js