دریافت مسیر

توسعه‌دهندگان منطقه اقتصادی اروپا (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() برای دریافت مسیر را نشان می‌دهد. ‫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 درخواست کرده‌اید فراخوانی کنید. نمایش چندخطی‌ها روی نقشه را ببینید.

فیلدهای موردنظر را برای برگرداندن انتخاب کنید

وقتی مسیری را درخواست می‌کنید، باید از ماسک فیلد برای مشخص کردن اطلاعاتی که پاسخ باید برگرداند استفاده کنید. می‌توانید نام‌های ویژگی‌های کلاس Route را در ماسک فیلد مشخص کنید.

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

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

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

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

  • استفاده از مختصات طول/عرض جغرافیایی می‌تواند باعث شود مکان به نزدیک‌ترین جاده به آن مختصات متصل شود - که ممکن است نقطه دسترسی به ملک نباشد، یا حتی جاده‌ای نباشد که سریع یا ایمن به مقصد منتهی شود.
  • رشته‌های نشانی ابتدا باید توسط 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.
};

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»). زمین‌کدیابی فرایند تبدیل رشته نشانی به مختصات عرض جغرافیایی و طول جغرافیایی است (مانند عرض جغرافیایی ۳۷٫۴۲۳۰۲۱ و طول جغرافیایی ۱۲۲٫۰۸۳۷۳۹-).

وقتی رشته نشانی را به‌عنوان مکان نقطه‌مسیر ارسال می‌کنید، کتابخانه 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'],
};

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 یکسان هستند، با چند استثنای قابل‌توجه. برای مثال، دامنه سطح بالای کد کشور پادشاهی متحد «uk»‏ (co.uk.) است، درحالی‌که کد ISO 3166-1 آن «gb» است (که ازنظر فنی برای نهاد «پادشاهی متحد بریتانیای کبیر و ایرلند شمالی» است).

درخواست مسیر برای «تولدو» به «مادرید» که شامل پارامتر regionCode است، نتایج مناسبی را برمی‌گرداند زیرا «تولدو» به‌عنوان شهری در اسپانیا تفسیر می‌شود:

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

Plus Code

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

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

Google Plus Codes را توسعه داده است تا همه افراد و چیزها بتوانند از مزایای آدرس بهره‌مند شوند. Plus Code مرجع مکان کدگذاری‌شده‌ای است که از مختصات طول/عرض جغرافیایی مشتق شده است و منطقه‌ای را نشان می‌دهد: ۱/۸۰۰۰ درجه در ۱/۸۰۰۰ درجه (حدود ۱۴ متر در ۱۴ متر در خط استوا) یا کوچک‌تر. در جاهایی که نشانی خیابان وجود ندارد یا ساختمان‌ها شماره‌گذاری نشده‌اند یا خیابان‌ها نام‌گذاری نشده‌اند، می‌توانید از Plus Codes به‌جای نشانی خیابان استفاده کنید.

Plus Code باید به‌صورت کد جهانی یا کد ترکیبی قالب‌بندی شود:

  • کد جهانی از یک کد منطقه ۴ نویسه‌ای و یک کد محلی ۶ نویسه‌ای یا طولانی‌تر تشکیل شده است. برای مثال، برای نشانی «1600 Amphitheatre Parkway, Mountain View, CA»، کد جهانی «849V» و کد محلی «CWC8+R9» است. سپس از کل Plus Code‏ ۱۰ نویسه‌ای برای مشخص کردن مقدار مکان به‌صورت «849VCWC8+R9» استفاده می‌کنید.
  • کد ترکیبی از یک کد محلی ۶ نویسه‌ای یا طولانی‌تر تشکیل شده است که با یک مکان صریح ترکیب شده است. برای مثال، نشانی «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'],
};

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