الحصول على مفتاح Maps Demo Key: يمكنك تجربة ميزات محدّدة من Maps JavaScript API و"حزمة أدوات خرائط Google الجاهزة للأماكن" بدون أي تكلفة باستخدام مفتاح Maps Demo Key، وبدون الحاجة إلى إدخال معلومات الفوترة.

تستخدم 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

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() للحصول على مسار. ‫computeRoutes() هي طريقة ثابتة لفئة Route، لذا يمكنك استدعاء Route.computeRoutes(request) مباشرةً. يجب أيضًا أن يضبط الطلب السمة fields على قناع حقل الاستجابة.

  // 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',
    fields: ['path'], // Required: response field mask.
  };

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

لرسم المسار على خريطة، يمكنك استدعاء createPolylines() على مسار طلبته باستخدام الحقل path. يمكنك الاطّلاع على عرض الخطوط المتعدّدة على خريطة.

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

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

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

حدِّد قائمة الحقول التي تحتاج إليها من خلال ضبط السمة 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

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

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

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

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

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

لتحديد موقع جغرافي باستخدام مكان، أنشِئ مثيلاً جديدًا من 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

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. يوضّح المقتطف التالي كيفية إنشاء مثيلات 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

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).

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

يعرض المقتطف التالي إنشاء 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

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 Code هو مرجع موقع جغرافي مرمّز، مشتق من إحداثيات خطوط العرض/الطول، ويمثّل منطقة: 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".

يوضّح المقتطف التالي كيفية احتساب مسار من خلال تحديد نقطة على المسار لنقطة انطلاق المسار ووجهته باستخدام 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

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

اختيار وسيلة نقل تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

TypeScript

JavaScript

CSS

HTML

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

TypeScript

JavaScript

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

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

TypeScript

JavaScript

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

TypeScript

JavaScript

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

TypeScript

JavaScript

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

رمز Plus Codes

TypeScript

JavaScript

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