Routes Preferred API در حال حاضر فقط برای مشتریان منتخب در دسترس است. برای کسب اطلاعات بیشتر
با واحد فروش تماس بگیرید.
Method: computeRouteMatrix
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
فهرستی از مبدا و مقصد را می گیرد و جریانی حاوی اطلاعات مسیر را برای هر ترکیب مبدا و مقصد برمی گرداند.
توجه: این روش مستلزم آن است که یک ماسک فیلد پاسخ را در ورودی مشخص کنید. می‌توانید ماسک فیلد پاسخ را با استفاده از پارامتر URL فیلدها یا fields $fields ، یا با استفاده از هدر HTTP/gRPC X-Goog-FieldMask تهیه کنید (به پارامترها و سرصفحه‌های URL موجود مراجعه کنید. مقدار فهرستی از مسیرهای فیلد است که با کاما از هم جدا شده‌اند. این مستندات دقیق در مورد نحوه ساخت مسیرهای فیلد را ببینید.
برای مثال در این روش:
- ماسک فیلد تمام فیلدهای موجود (برای بازرسی دستی):
X-Goog-FieldMask: * - ماسک میدانی از مدت‌زمان مسیر، مسافت‌ها، وضعیت عنصر، وضعیت و شاخص‌های عنصر (نمونه‌ای از راه‌اندازی تولید):
X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration
بسیار مهم است که status در ماسک فیلد خود وارد کنید زیرا در غیر این صورت همه پیام‌ها درست به نظر می‌رسند. گوگل استفاده از ماسک فیلد پاسخ ( * ) را منع می کند، زیرا:
- انتخاب فقط فیلدهایی که نیاز دارید به سرور ما کمک می کند تا چرخه های محاسباتی را ذخیره کند و به ما امکان می دهد نتیجه را با تاخیر کمتری به شما برگردانیم.
- انتخاب تنها زمینه هایی که در کار تولیدی خود به آن نیاز دارید، عملکرد تاخیر پایدار را تضمین می کند. ممکن است در آینده فیلدهای پاسخ بیشتری اضافه کنیم و این فیلدهای جدید ممکن است به زمان محاسبات اضافی نیاز داشته باشند. اگر همه فیلدها را انتخاب کنید، یا اگر همه فیلدها را در سطح بالا انتخاب کنید، ممکن است با کاهش عملکرد مواجه شوید زیرا هر فیلد جدیدی که اضافه کنیم به طور خودکار در پاسخ گنجانده می شود.
- انتخاب تنها فیلدهایی که به آنها نیاز دارید باعث می‌شود که اندازه پاسخ کوچک‌تر و در نتیجه توان عملیاتی شبکه بیشتر شود.
درخواست HTTP
POST https://routespreferred.googleapis.com/v1alpha:computeRouteMatrix
URL از دستور GRPC Transcoding استفاده می کند.
درخواست بدن
بدنه درخواست حاوی داده هایی با ساختار زیر است:
| فیلدها |
|---|
origins[] | object ( RouteMatrixOrigin ) مورد نیاز. آرایه مبدا، که ردیف های ماتریس پاسخ را تعیین می کند. چندین محدودیت اندازه برای اصلی بودن مبدا و مقصد اعمال می شود: - تعداد عناصر (منشا × مقصد) در هر صورت نباید بیشتر از 625 باشد.
- اگر routingPreference روی
TRAFFIC_AWARE_OPTIMAL تنظیم شده باشد، تعداد عناصر (مبداء × مقصد) نباید بیشتر از 100 باشد. - تعداد نقاط راه (مبداء + مقصد) مشخص شده به عنوان
placeId نباید بیشتر از 50 باشد.
|
destinations[] | object ( RouteMatrixDestination ) مورد نیاز. آرایه ای از مقاصد، که ستون های ماتریس پاسخ را تعیین می کند. |
travel Mode | enum ( RouteTravelMode ) اختیاری. نحوه حمل و نقل را مشخص می کند. |
routing Preference | enum ( RoutingPreference ) اختیاری. نحوه محاسبه مسیر را مشخص می کند. سرور سعی می کند از اولویت مسیریابی انتخاب شده برای محاسبه مسیر استفاده کند. اگر اولویت مسیریابی منجر به خطا یا تاخیر طولانی مدت شود، یک خطا برگردانده می شود. شما می توانید این گزینه را فقط زمانی مشخص کنید که travelMode DRIVE یا TWO_WHEELER باشد، در غیر این صورت درخواست با شکست مواجه می شود. |
departure Time | string ( Timestamp format) اختیاری. زمان حرکت اگر این مقدار را تنظیم نکنید، به طور پیش‌فرض روی زمانی است که درخواست را انجام داده‌اید. اگر این مقدار را روی زمانی تنظیم کنید که قبلاً اتفاق افتاده است، درخواست با شکست مواجه می شود. یک مهر زمانی در قالب RFC3339 UTC "Zulu"، با وضوح نانوثانیه و حداکثر نه رقم کسری. مثال‌ها: "2014-10-02T15:01:23Z" و "2014-10-02T15:01:23.045123456Z" . |
بدن پاسخگو
در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی جریانی از نمونه های RouteMatrixElement است.
محدوده مجوز
به محدوده OAuth زیر نیاز دارد:
-
https://www.googleapis.com/auth/maps-platform.routespreferred
برای اطلاعات بیشتر، به نمای کلی OAuth 2.0 مراجعه کنید.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eTakes a list of origins and destinations, returning route information for each combination.\u003c/p\u003e\n"],["\u003cp\u003eRequires specifying a response field mask for optimized performance and data selection.\u003c/p\u003e\n"],["\u003cp\u003eAccepts parameters for travel mode, routing preference, and departure time.\u003c/p\u003e\n"],["\u003cp\u003eReturns a stream of \u003ccode\u003eRouteMatrixElement\u003c/code\u003e instances containing route details.\u003c/p\u003e\n"],["\u003cp\u003eRequires the \u003ccode\u003ehttps://www.googleapis.com/auth/maps-platform.routespreferred\u003c/code\u003e OAuth scope for authorization.\u003c/p\u003e\n"]]],["This method computes route information for multiple origin-destination pairs. It requires a `POST` request to `computeRouteMatrix` with lists of `origins` and `destinations` in the request body. A field mask must be included to specify which data fields to return, with `status` being critical. Optional parameters include `travelMode`, `routingPreference`, and `departureTime`. The response is a stream of `RouteMatrixElement` instances, and the method requires a specific OAuth scope for authorization.\n"],null,["# Method: computeRouteMatrix\n\n- [HTTP request](#body.HTTP_TEMPLATE)\n- [Request body](#body.request_body)\n - [JSON representation](#body.request_body.SCHEMA_REPRESENTATION)\n- [Response body](#body.response_body)\n- [Authorization scopes](#body.aspect)\n\nTakes in a list of origins and destinations and returns a stream containing route information for each combination of origin and destination.\n\n**NOTE:** This method requires that you specify a response field mask in the input. You can provide the response field mask by using the URL parameter `$fields` or `fields`, or by using the HTTP/gRPC header `X-Goog-FieldMask` (see the [available URL parameters and headers](https://cloud.google.com/apis/docs/system-parameters). The value is a comma separated list of field paths. See this detailed documentation about [how to construct the field paths](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto).\n\nFor example, in this method:\n\n- Field mask of all available fields (for manual inspection): `X-Goog-FieldMask: *`\n- Field mask of route durations, distances, element status, condition, and element indices (an example production setup): `X-Goog-FieldMask:\n originIndex,destinationIndex,status,condition,distanceMeters,duration`\n\nIt is critical that you include `status` in your field mask as otherwise all messages will appear to be OK. Google discourages the use of the wildcard (`*`) response field mask, because:\n\n- Selecting only the fields that you need helps our server save computation cycles, allowing us to return the result to you with a lower latency.\n- Selecting only the fields that you need in your production job ensures stable latency performance. We might add more response fields in the future, and those new fields might require extra computation time. If you select all fields, or if you select all fields at the top level, then you might experience performance degradation because any new field we add will be automatically included in the response.\n- Selecting only the fields that you need results in a smaller response size, and thus higher network throughput.\n\n### HTTP request\n\n`POST https://routespreferred.googleapis.com/v1alpha:computeRouteMatrix`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Request body\n\nThe request body contains data with the following structure:\n\n| JSON representation |\n|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"origins\": [ { object (/maps/documentation/routes_preferred/reference/rest/Shared.Types/ComputeRouteMatrixRequest#RouteMatrixOrigin) } ], \"destinations\": [ { object (/maps/documentation/routes_preferred/reference/rest/Shared.Types/ComputeRouteMatrixRequest#RouteMatrixDestination) } ], \"travelMode\": enum (/maps/documentation/routes_preferred/reference/rest/Shared.Types/RouteTravelMode), \"routingPreference\": enum (/maps/documentation/routes_preferred/reference/rest/Shared.Types/RoutingPreference), \"departureTime\": string } ``` |\n\n| Fields ||\n|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `origins[]` | `object (`[RouteMatrixOrigin](/maps/documentation/routes_preferred/reference/rest/Shared.Types/ComputeRouteMatrixRequest#RouteMatrixOrigin)`)` Required. Array of origins, which determines the rows of the response matrix. Several size restrictions apply to the cardinality of origins and destinations: - The number of elements (origins × destinations) must be no greater than 625 in any case. - The number of elements (origins × destinations) must be no greater than 100 if routingPreference is set to `TRAFFIC_AWARE_OPTIMAL`. - The number of waypoints (origins + destinations) specified as `placeId` must be no greater than 50. |\n| `destinations[]` | `object (`[RouteMatrixDestination](/maps/documentation/routes_preferred/reference/rest/Shared.Types/ComputeRouteMatrixRequest#RouteMatrixDestination)`)` Required. Array of destinations, which determines the columns of the response matrix. |\n| `travel``Mode` | `enum (`[RouteTravelMode](/maps/documentation/routes_preferred/reference/rest/Shared.Types/RouteTravelMode)`)` Optional. Specifies the mode of transportation. |\n| `routing``Preference` | `enum (`[RoutingPreference](/maps/documentation/routes_preferred/reference/rest/Shared.Types/RoutingPreference)`)` Optional. Specifies how to compute the route. The server attempts to use the selected routing preference to compute the route. If the routing preference results in an error or an extra long latency, an error is returned. You can specify this option only when the `travelMode` is `DRIVE` or `TWO_WHEELER`, otherwise the request fails. |\n| `departure``Time` | `string (`[Timestamp](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp)` format)` Optional. The departure time. If you don't set this value, this defaults to the time that you made the request. If you set this value to a time that has already occurred, the request fails. A timestamp in RFC3339 UTC \"Zulu\" format, with nanosecond resolution and up to nine fractional digits. Examples: `\"2014-10-02T15:01:23Z\"` and `\"2014-10-02T15:01:23.045123456Z\"`. |\n\n### Response body\n\nIf successful, the response body contains a stream of [RouteMatrixElement](/maps/documentation/routes_preferred/reference/rest/Shared.Types/RouteMatrixElement) instances.\n\n### Authorization scopes\n\nRequires the following OAuth scope:\n\n- `https://www.googleapis.com/auth/maps-platform.routespreferred`\n\nFor more information, see the [OAuth 2.0 Overview](https://developers.google.com/identity/protocols/OAuth2)."]]
