دریافت مسیر

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

مسیر عبارت است از مسیری پیمایش‌پذیر بین مکان شروع، یا مبدأ، و مکان پایان، یا مقصد. می‌توانید مسیری برای حالت‌های مختلف حمل‌ونقل، مثل پیاده‌روی، دوچرخه‌سواری، یا انواع مختلف وسایل نقلیه دریافت کنید. همچنین می‌توانید جزئیات مسیر مثل فاصله، زمان تخمینی پیمایش مسیر، عوارض موردانتظار، و دستورالعمل‌های گام‌به‌گام پیمایش مسیر را درخواست کنید.

دیدن کد منبع نمونه کامل

نمونه کد زیر نحوه دریافت مسیر برای مسیرهای رانندگی بین دو مکان را نشان می‌دهد.

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();

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();

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;
}

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>

برای درخواست مسیر بین دو مکان، روش 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 دارایی، همان‌طور که در گزیده زیر نشان داده شده است، فهرست فیلدهای موردنیازتان را مشخص کنید:

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.
};

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.
};

مکان‌های مسیر را مشخص کنید

برای محاسبه مسیر، باید حداقل مکان‌های مبدأ و مقصد مسیر و یک پوشش فیلد را مشخص کنید. همچنین می‌توانید ایستگاه‌های بین راهی درطول مسیر مشخص کنید و از ایستگاه‌های بین راهی برای انجام کارهای دیگر مثل افزودن توقف یا نقاط عبور درطول مسیر استفاده کنید.

در ComputeRoutesRequest، می‌توانید مکان را به هریک از روش‌های زیر مشخص کنید:

می‌توانید مکان‌ها را برای همه ایستگاه‌های بین راه در یک درخواست به یک روش مشخص کنید، یا می‌توانید آن‌ها را ترکیب کنید. برای مثال، می‌توانید از مختصات طول/عرض جغرافیایی برای ایستگاه بین راهی مبدأ و از «مکان» برای ایستگاه بین راهی مقصد استفاده کنید.

برای کارایی و دقت، به‌جای مختصات طول/عرض جغرافیایی یا رشته‌های نشانی، از اشیا «مکان» استفاده کنید. شناسه‌های مکان منحصربه‌فرد و صریح هستند و مزایای زمین‌کدگذاری برای مسیریابی مثل نقاط دسترسی و متغیرهای ترافیک ارائه می‌دهند. این مکان‌ها به جلوگیری از موقعیت‌های زیر کمک می‌کنند که می‌تواند از روش‌های دیگر مشخص کردن مکان ناشی شود:

  • استفاده از مختصات طول/عرض جغرافیایی می‌تواند منجر به این شود که مکان به نزدیک‌ترین جاده به آن مختصات چسبانده شود - که ممکن است نقطه دسترسی به ملک نباشد، یا حتی جاده‌ای نباشد که به‌سرعت یا ایمن به مقصد برسد.
  • رشته‌های نشانی باید ابتدا توسط «میانای برنامه‌سازی کاربردی مسیرها» زمین‌کدگذاری شوند تا به مختصات عرض جغرافیایی/طول جغرافیایی تبدیل شوند و سپس بتواند مسیر را محاسبه کند. این تبدیل می‌تواند بر عملکرد تأثیر بگذارد.

مکان را به‌عنوان شیء «مکان» مشخص کنید (ترجیح داده می‌شود)

برای مشخص کردن مکان بااستفاده از «مکان»، نمونه 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.
};

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.
};

مختصات طول/عرض جغرافیایی

برای مشخص کردن مکان به‌عنوان مختصات طول/عرض جغرافیایی، نمونه جدیدی از 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'],
};

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'],
};

رشته نشانی

رشته‌های نشانی نشانی‌های واقعی هستند که با رشته‌ای نشان داده می‌شوند (مثل «1600 Amphitheatre Parkway, Mountain View, CA»). «زمین‌کدگذاری» فرایند تبدیل رشته نشانی به مختصات عرض جغرافیایی و طول جغرافیایی (مثل عرض جغرافیایی ۳۷٫۴۲۳۰۲۱ و طول جغرافیایی ۱۲۲٫۰۸۳۷۳۹-) است.

وقتی رشته نشانی را به‌عنوان مکان ایستگاه بین راهی ارسال می‌کنید، کتابخانه «مسیرها» رشته را به‌صورت داخلی زمین‌کد می‌کند تا آن را به مختصات طول و عرض جغرافیایی تبدیل کند.

تکه زیر ایجاد 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'],
};

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'],
};

منطقه نشانی را تنظیم کنید

اگر رشته نشانی ناقصی را به‌عنوان مکان ایستگاه بین راهی ارسال کنید، ممکن است «میانای برنامه‌سازی کاربردی» از مختصات عرض/طول جغرافیایی زمین‌کدیابی‌شده اشتباه استفاده کند. برای مثال، درخواستی ارائه می‌کنید که در آن «تولدو» را به‌عنوان مبدأ و «مادرید» را به‌عنوان مقصد برای مسیر رانندگی مشخص می‌کنید:

// 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 Code

بسیاری از افراد نشانی دقیق ندارند، که می‌تواند دریافت ارسال‌ها را برای آن‌ها دشوار کند. یا، افراد دارای نشانی ممکن است ترجیح دهند تحویل در مکان‌های دقیق‌تر انجام شود، مثلاً در ورودی پشتی یا بارانداز.

«کدهای باز» مانند نشانی خیابان برای افراد یا مکان‌هایی هستند که نشانی واقعی ندارند. به‌جای نشانی‌های دارای نام خیابان و شماره، «کدهای پلاس» براساس مختصات عرض/طول جغرافیایی هستند و به‌صورت اعداد و حروف نمایش داده می‌شوند.

‫Google کدهای پلاس را توسعه داده است تا مزایای نشانی را برای همه و همه چیز فراهم کند. «کد پلاس» یک مرجع مکان کدبندی‌شده است که از مختصات طول/عرض جغرافیایی استخراج می‌شود و نشان‌دهنده یک منطقه است: یک‌هشت‌هزارم درجه در یک‌هشت‌هزارم درجه (حدود ۱۴ متر × ۱۴ متر در خط استوا) یا کوچک‌تر. در مکان‌هایی که نشانی خیابان وجود ندارد یا ساختمان‌ها شماره‌گذاری نشده‌اند یا خیابان‌ها نام‌گذاری نشده‌اند، می‌توانید از «کدهای پلاس» به‌عنوان جایگزین نشانی خیابان استفاده کنید.

«کدهای پستی پلاس» باید به‌صورت کد جهانی یا کد ترکیبی قالب‌بندی شوند:

  • کد جهانی از پیش‌شماره ۴ نویسه‌ای و کد محلی ۶ نویسه‌ای یا طولانی‌تر تشکیل شده است. برای مثال، برای نشانی «1600 Amphitheatre Parkway, Mountain View, CA»، کد جهانی «849V» و کد محلی «CWC8+R9» است. سپس از کل ۱۰ نویسه «کد پلاس» برای مشخص کردن مقدار مکان به‌عنوان «849VCWC8+R9» استفاده می‌کنید.
  • کد ترکیبی از یک کد محلی ۶ کاراکتری یا طولانی‌تر که با یک مکان صریح ترکیب شده است تشکیل می‌شود. برای مثال، نشانی «450 Serra Mall, Stanford, CA 94305, USA» کد محلی «CRHJ+C3» دارد. برای نشانی مرکب، کد محلی را با شهر، ایالت، کد پستی، و بخش کشور نشانی در قالب «CRHJ+C3 Stanford, CA 94305, USA» ترکیب کنید.

تکه کد زیر نشان می‌دهد که چگونه با مشخص کردن نقطه توقف برای مبدأ و مقصد مسیر بااستفاده از «کدهای پلاس» مسیر محاسبه می‌شود:

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'],
};

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'],
};