با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
گاهی اوقات، ممکن است بخواهید مسیری را که برنامه شما در اختیار کاربران قرار می دهد، برنامه ریزی کنید. استفاده از نشانه مسیر از Routes API، Routes Preferred API، یا Route Optimization API می تواند به شما کمک کند تا دو مورد را برای مسیر برنامه ریزی شده خود مشخص کنید:
پلی لاین برای مسیر
اهداف مسیر شما
به عنوان مثال، در اینجا چند نمونه از اهداف مسیریابی که ممکن است داشته باشید آورده شده است:
زمان تحویل را به حداقل برسانید : یک کسب و کار تحویل غذا ممکن است بخواهد زمان تحویل غذا را به حداقل برساند.
زمان سفر یا مصرف سوخت را به حداقل برسانید : یک تجارت لجستیک ممکن است بخواهد کارایی رانندگان خود را بهبود بخشد و هزینه سوخت آنها را کاهش دهد.
زمان رسیدن به مقصد را به حداقل برسانید : یک عملیات ارسال خدمات ممکن است بخواهد زمان لازم برای رسیدن اپراتورها به درخواست کار را به حداقل برساند.
هزینه های کمتر و بهبود ایمنی : یک کسب و کار اشتراک سوار ممکن است بخواهد مسیری را پیدا کند که هزینه کمتری برای سوارکاران داشته باشد و به دلایل ایمنی از مناطق خاصی اجتناب کند.
با یک نشانه مسیر از Routes API، Routes Preferred API، یا Route Optimization API، کنترل بیشتری روی مسیر ارائه شده دارید:
از قبل مسیری را برای Navigation SDK برنامه ریزی کنید تا در صورت امکان از آن استفاده کنید.
بهترین مسیر را برای استفاده از Navigation SDK انتخاب کنید . اگر هنگام ایجاد مسیرها در Routes API، توکن های مسیر را درخواست کنید، برای هر مسیر تولید شده یک نشانه مسیر دریافت می کنید. سپس می‌توانید رمزی را برای مسیری که می‌خواهید هنگام ارسال آن به Navigation SDK استفاده کنید، انتخاب کنید.
قیمت را از قبل، از جمله برآورد ETA و مسافت، تخمین بزنید . در حالی که هزینه و زمان واقعی ممکن است متفاوت باشد، این برآورد فاصله بین هزینه مورد انتظار و هزینه واقعی مسیر را کاهش می دهد.
اهداف مسیر پیشرفته‌تری مانند مسیریابی سازگار با محیط زیست یا کوتاه‌ترین مسیر را مشخص کنید .
نحوه عملکرد توکن های مسیر
می‌توانید از Routes API، Routes Preferred API یا Route Optimization API برای برنامه‌ریزی مسیر با استفاده از اهداف مسیر استفاده کنید. می‌توانید یک نشانه مسیری که از هر یک از این APIها بازگردانده شده است را به Navigation SDK ارسال کنید تا نحوه مسیریابی وسیله نقلیه شما را راهنمایی کنید.
هنگامی که یک نشانه مسیر را درخواست می کنید و از آن استفاده می کنید چه اتفاقی می افتد:
Routes API، Routes Preferred API یا Route Optimization یک نشانه مسیر رمزگذاری شده را برمی گرداند که شامل چند خط مسیر و اهداف مسیر است.
رمز مسیر را به Navigation SDK منتقل می کنید.
Navigation SDK مسیر را بازیابی می کند یا اگر مسیر به دلیل تغییر شرایط موجود نباشد، بهترین مسیر منطبق را بازیابی می کند.
در حین رانندگی مسیر، اگر ترافیک یا سایر شرایط جاده تغییر کند، یا اگر وسیله نقلیه از مسیر برنامه ریزی شده منحرف شود، مسیرهای اصلاح شده به طور مداوم تلاش می کنند تا بهترین مسیر را بر اساس اهداف مسیر در نشانه مطابقت دهند.
این فرآیند میزان نزدیکی مسیر واقعی به مسیر برنامه ریزی شده شما را به حداکثر می رساند.
چرا یک مسیر برنامه ریزی شده ممکن است دقیقا دنبال نشود
مسیر برنامه ریزی شده و اهداف مسیر خود را به عنوان دستورالعمل هایی که باید دنبال کنید در نظر بگیرید: آنها تجویزی نیستند. ممکن است به دلیل تفاوت در شرایط جاده، مکان شروع یا سایر پارامترهایی که از زمان ایجاد مسیر برنامه ریزی شده تغییر کرده است، بین مسیر برنامه ریزی شده خود و مسیر ارائه شده توسط ناوبری هدایت شده تفاوت مشاهده کنید. این تفاوت ممکن است منجر به عدم تطابق بین اهداف برنامه ریزی شده و واقعی شما برای مسافت و ETA، در میان سایر ویژگی های مهم سفر شود.
یک مسیر را با استفاده از نشانه مسیر برنامه ریزی کنید
همانطور که در مراحل زیر توضیح داده شده است، می توانید یک مسیر را با ایجاد یک نشانه مسیر و سپس ارسال آن به Navigation SDK برنامه ریزی کنید:
مرحله 1: با استفاده از Routes API، Routes Preferred API یا Route Optimization یک نشانه مسیر ایجاد کنید.
یک نشانه مسیر را با یکی از روش های زیر درخواست کنید :
Routes API : computeRoutes . برای اطلاعات بیشتر درباره درخواست نشانه مسیر در Routes API، به محاسبه مسیر و درخواست نشانه مسیر مراجعه کنید.
Routes Preferred API : computeCustomRoutes . برای اطلاعات بیشتر درباره درخواست نشانه مسیر در Routes Preferred API، به برنامه ریزی مسیر مراجعه کنید.
Route Optimization API : optimizeTours یا batchOptimizeTours . برای اطلاعات بیشتر در مورد درخواست نشانه مسیر در Route Optimization API، به Polylines و Route Tokens Transition مراجعه کنید.
Routes API یا Routes Preferred API درخواست خود را برای برآورده کردن الزامات استفاده از یک نشانه مسیر تنظیم کنید :
travel_mode روی DRIVING یا TWO_WHEELER تنظیم کنید
routing_preference را روی TRAFFIC_AWARE یا TRAFFIC_AWARE_OPTIMAL تنظیم کنید
Via ایستگاه های بین راه استفاده نکنید
مرحله 2: رمز مسیر را به Navigation SDK منتقل کنید
ذخیره نشانه مسیر : در Navigation SDK، یک رشته برای ذخیره نشانه مسیر تنظیم کنید. به عنوان مثال:
letrouteToken="route token returned by Routes API"
نمونه ای از نشانه مسیر برگشتی:
{// Other fields"routeToken":"CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",}
رمز مسیر را با استفاده از روش mapView.navigator setDestinations به Navigation SDK منتقل کنید و همان نقاط بین مقصدی را که هنگام ایجاد نشانه مسیر استفاده کردید مشخص کنید:
مثال های کد زیر نحوه بازیابی یک مسیر برنامه ریزی شده را نشان می دهد.
سویفت
letlocation=CLLocationCoordinate2D(latitude:47.67,longitude:-122.20)letwaypoint1=GMSNavigationWaypoint(location:location,title:"waypoint from location")!letwaypoint2=GMSNavigationWaypoint(placeID:"samplePlaceID",title:"waypoint from Place ID")!letrouteToken="route token returned by Routes API"mapView.navigator?.setDestinations([waypoint1,waypoint2],routeToken:routeToken,callback:{...})
هدف-C
CLLocationCoordinate2Dlocation=CLLocationCoordinate2DMake(47.67,-122.20);GMSNavigationWaypoint*waypoint1=[[GMSNavigationWaypointalloc]initWithLocation:coordinatetitle:@"waypoint from location"];GMSNavigationWaypoint*waypoint2=[[GMSNavigationWaypointalloc]initWithPlaceID:@"samplePlaceID"title:@"waypoint from Place ID"];NSString*routeToken=@"route token returned by Routes API";[mapView.navigatorsetDestinations:@[waypoint1,waypoint2]routeToken:routeTokencallback:^(GMSRouteStatusrouteStatus){...}];
نحوه تعامل نشانه‌های مسیر و Navigation SDK
در اینجا نحوه تعامل مسیر تولید شده توسط Navigation SDK و مسیر برنامه ریزی شده در نشانه مسیر آمده است:
گزینه های مرتبط با مسیریابی زیر را به عنوان غیر ضروری نادیده می گیرد :
avoidsHighways
avoidsTolls
avoidsFerries
licensePlateRestriction
دنبال می کند :
گزینه‌های مرتبط با ایستگاه‌های راه ، مانند ترجیح کنار جاده.
اهداف مسیر اگر Navigation SDK باید مسیر برگشتی را تنظیم کند، از اهداف مسیری که هنگام درخواست نشانه مسیر مشخص کرده‌اید استفاده می‌کند. به همین دلیل، باید از همان گزینه های مربوط به ایستگاه بین راه استفاده کنید که در Routes API مشخص کرده اید.
تاریخ آخرین بهروزرسانی 2025-09-03 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-09-03 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eRoute tokens let you plan routes in advance, optimizing for factors like time, fuel, or safety, and can be generated using the Routes, Routes Preferred, or Route Optimization API.\u003c/p\u003e\n"],["\u003cp\u003eWhile the Navigation SDK attempts to follow the planned route, real-world conditions may cause deviations; it dynamically adjusts while prioritizing the specified route objectives.\u003c/p\u003e\n"],["\u003cp\u003eYou create a route token via the Routes, Routes Preferred, or Route Optimization API, then pass it to the Navigation SDK's \u003ccode\u003esetDestinations\u003c/code\u003e method alongside your waypoints.\u003c/p\u003e\n"],["\u003cp\u003eThe Navigation SDK prioritizes the route token's plan but dynamically adapts to real-time conditions, potentially leading to variations between the planned and actual route.\u003c/p\u003e\n"],["\u003cp\u003eAlways request a fresh route token for each trip and anticipate potential route adjustments to ensure smooth navigation and accurate estimations.\u003c/p\u003e\n"]]],[],null,["# Plan a route\n\nAt times, you might want to plan the route your app provides to users. Using a\nroute token from the Routes API,\nRoutes Preferred API, or Route Optimization API can\nhelp you specify two things for your planned route:\n\n- A polyline for the route\n\n- Your route objectives\n\nFor example, here are some examples of routing objectives you may have:\n\n- **Minimize time to delivery**: A business delivering food might want to\n minimize the time it takes to deliver the food.\n\n- **Minimize travel time or fuel consumption**: A logistics business might\n want to improve the efficiency of their drivers and reduce their fuel costs.\n\n- **Minimize time to destination**: A service dispatch operation might want to\n minimize the time it takes to get operators to a job request.\n\n- **Lower costs and improve safety**: A ride-sharing business might want to\n find a route that costs less for riders and avoids certain areas for safety\n reasons.\n\n| **Important:** The actual route traveled may vary from the planned route provided by the token. Changing traffic, road conditions, or the vehicle deviating from the given route can result in route changes. As changes occur, the Navigation SDK continually attempts to return to the planned route, or if returning is impractical, follows the route objectives in the route token.\n\nFor more information about planning a route using a route token, see [Request a\nroute token](/maps/documentation/routes/choose_fields#route-token) in\nRoutes API and [Transition Polylines and Route\nTokens](/maps/documentation/route-optimization/polylines-and-route-tokens) in\nRoute Optimization API.\n\nWhy use a route token for route objectives\n------------------------------------------\n\nWith a route token from the Routes API,\nRoutes Preferred API, or Route Optimization API, you\nhave more control over the route provided:\n\n- **Plan a route in advance** for the Navigation SDK to use when\n possible.\n\n- **Choose the best route for the Navigation SDK to use**. If you\n request route tokens when generating routes in the Routes API,\n you get a route token for each generated route. You can then choose the\n token for the route you want to use when you pass it to the\n Navigation SDK.\n\n- **Estimate the price in advance**, including estimations for ETA and\n distance. While the actual cost and time might vary, this estimation reduces\n the gap between expected and actual route cost.\n\n- **Specify more advanced route objectives**, such as eco routing or the\n shortest route.\n\n| **Tip:** A route token is for one specific origin and destination and at a particular time. You must make a new Routes API, Routes Preferred API, or Route Optimization API request for a new route token.\n\nHow route tokens work\n---------------------\n\nYou can use the Routes API, Routes Preferred API, or\nRoute Optimization API to plan a route using route objectives. You\ncan pass a route token returned from any of these APIs to the\nNavigation SDK to guide how it routes your vehicle.\n\nHere's what happens when you request and use a route token:\n\n1. The Routes API, Routes Preferred API, or\n Route Optimization API returns an encrypted route token that\n includes the route polyline and route objectives.\n\n2. You pass the route token to the Navigation SDK.\n\n3. The Navigation SDK retrieves the route, or if the route is not\n available due to changing conditions, it retrieves the best matching route.\n\n4. While driving the route, if traffic or other road conditions change, or if a\n vehicle deviates from the planned route, the modified routes continually\n attempt to match the best route based on the route objectives in the token.\n\nThis process maximizes how close the actual route is to your planned route.\n\n### Why a planned route may not be followed exactly\n\nThink of your planned route and route objectives as guidelines to follow: they\nare not prescriptive. You might see a difference between your planned route and\nthe route provided by guided navigation due to differences in the road\nconditions, starting location, or other parameters that have changed since you\ncreated the planned route. This difference might result in a mismatch between\nyour planned and actual goals for distance and ETA, among other important trip\nqualities.\n| **Tip:** As a best practice, always request a new route token every time you set the destination in the Navigation SDK, and plan for some variation to avoid any impact to your business.\n\nPlan a route using a route token\n--------------------------------\n\nYou can plan a route by creating a route token and then passing it to the\nNavigation SDK, as described in the following steps:\n\n### Step 1: Create a route token using the Routes API, Routes Preferred API, or Route Optimization API\n\n1. **Request a route token** with one of the following methods:\n\n - **Routes API** : `computeRoutes`. For more information\n about requesting a route token in the Routes API, see\n [Compute a route](/maps/documentation/routes/compute_route_directions)\n and [Request a route\n token](/maps/documentation/routes/choose_fields#route-token).\n\n - **Routes Preferred API** : `computeCustomRoutes`. For more\n information about requesting a route token in the\n Routes Preferred API, see [Plan a\n route](/maps/documentation/routes_preferred/custom_routes).\n\n - **Route Optimization API** : `optimizeTours` or\n `batchOptimizeTours`. For more information about requesting a route\n token in the Route Optimization API, see [Transition Polylines and Route\n Tokens](/maps/documentation/route-optimization/polylines-and-route-tokens).\n\n2. **Set up your Routes API or Routes Preferred API\n request** to meet the requirements for using a route token:\n\n - Set `travel_mode` to `DRIVING` or `TWO_WHEELER`\n - Set `routing_preference` to `TRAFFIC_AWARE` or `TRAFFIC_AWARE_OPTIMAL`\n - Do NOT use `Via` waypoints\n\n### Step 2: Pass the route token to the Navigation SDK\n\n1. **Store the route token**: In the Navigation SDK, set up a string\n to store the route token. For example:\n\n let routeToken = \"route token returned by Routes API\"\n\n Example of a returned route token: \n\n {\n // Other fields\n \"routeToken\": \"CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g\",\n }\n\n2. **Pass the route token** to the Navigation SDK using the\n `mapView.navigator setDestinations` method, specifying the same destination\n waypoints that you used when creating the route token:\n\n mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})\n\n| **Note:** If you need to travel the same route again, request a new route token.\n\nThe `Navigator.setDestinations` method returns the status of the request.\nIf a route is found from the user's location to the given destination,\nit returns`RouteStatus.OK`.\n\nFor more information about this method, see\n[`GMSNavigator.setDestinations`](/maps/documentation/navigation/ios-sdk/reference/objc/Classes/GMSNavigator#-setdestinations:callback:).\n\n### Example\n\nThe following code examples demonstrate how to retrieve a planned route.\n\n\u003cbr /\u003e\n\n### Swift\n\n\u003cbr /\u003e\n\n let location = CLLocationCoordinate2D(latitude: 47.67, longitude: -122.20)\n let waypoint1 = GMSNavigationWaypoint(location: location, title: \"waypoint from location\")!\n let waypoint2 = GMSNavigationWaypoint(placeID: \"samplePlaceID\", title: \"waypoint from Place ID\")!\n\n let routeToken = \"route token returned by Routes API\"\n mapView.navigator?.setDestinations([waypoint1, waypoint2], routeToken: routeToken, callback: {...})\n\n\u003cbr /\u003e\n\n### Objective-C\n\n\u003cbr /\u003e\n\n CLLocationCoordinate2D location = CLLocationCoordinate2DMake(47.67, -122.20);\n GMSNavigationWaypoint *waypoint1 = [[GMSNavigationWaypoint alloc] initWithLocation:coordinate title:@\"waypoint from location\"];\n GMSNavigationWaypoint *waypoint2 = [[GMSNavigationWaypoint alloc] initWithPlaceID:@\"samplePlaceID\"\n title:@\"waypoint from Place ID\"];\n NSString *routeToken = @\"route token returned by Routes API\";\n\n [mapView.navigator setDestinations:@[waypoint1, waypoint2]\n routeToken:routeToken\n callback:^(GMSRouteStatus routeStatus){...}];\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nHow route tokens and the Navigation SDK interact\n------------------------------------------------\n\nHere's how the route generated by the Navigation SDK and the planned\nroute in the route token interact:\n\n- **Overrides** any previously-set destinations.\n\n- **Uses** the vehicle starting location.\n\n- **Adjusts** for road and traffic conditions. See\n [Why a planned route might not be followed exactly](#not-followed).\n\n- **Ignores** the following routing-related options as unneeded:\n\n - `avoidsHighways`\n - `avoidsTolls`\n - `avoidsFerries`\n - `licensePlateRestriction`\n- **Follows**:\n\n - **Waypoint-related options**, such as the side-of-road preference.\n\n - **Route objectives**. If the Navigation SDK has to\n adjust the returned route, it uses the route objectives you specified when\n requesting the route token. For this reason, you should use the same\n waypoint-related options that you specified in Routes API."]]
