Truyền tham số routingParameters.origin trong yêu cầu để chỉ định toạ độ vĩ độ và kinh độ của điểm bắt đầu định tuyến. Tham số này là bắt buộc để tính toán thời lượng và khoảng cách đến từng địa điểm trong phản hồi.
Thêm routingSummaries vào mặt nạ trường để phản hồi bao gồm mảng routingSummaries. Mảng này chứa thời lượng và khoảng cách từ điểm bắt đầu định tuyến đến từng địa điểm trong phản hồi.
API Explorer cho phép bạn đưa ra các yêu cầu trực tiếp để có thể làm quen với API và các lựa chọn API:
Phản hồi chứa 2 mảng JSON: mảng places chứa các địa điểm trùng khớp và mảng routingSummaries chứa thời lượng và khoảng cách di chuyển đến từng địa điểm:
Mỗi phần tử trong mảng routingSummaries nằm ở vị trí mảng tương ứng với vị trí trong mảng places. Tức là phần tử tại routingSummaries[0] tương ứng với vị trí tại places[0].
Độ dài mảng của routingSummaries giống với độ dài mảng của places. Trong trường hợp không có routingSummary cho một địa điểm, mục nhập mảng sẽ trống.
Vì ví dụ này tính toán thời lượng và khoảng cách từ điểm bắt đầu định tuyến đến từng địa điểm, nên trường routingSummaries.legs trong phản hồi chứa một đối tượng Leg duy nhất chứa duration và distanceMeters từ điểm bắt đầu định tuyến đến địa điểm.
{"places":[{"formattedAddress":"1, Westfield Sydney Central Plaza, 450 George St, Sydney NSW 2000, Australia","displayName":{"text":"Gözleme King Sydney","languageCode":"en"}},{"formattedAddress":"367 Pitt St, Sydney NSW 2000, Australia","priceLevel":"PRICE_LEVEL_MODERATE","displayName":{"text":"Mother Chu's Vegetarian Kitchen","languageCode":"en"}},…]"routingSummaries":[{"legs":[{"duration":"597s","distanceMeters":2607}],"directionsUri":"https://www.google.com/maps/dir/-33.8688,151.1957362/''/data=!4m6!4m5!1m0!1m2!1m1!1s0x6b12ae3fa97cd745:0x6aecf365bf497c08!3e0"},{"legs":[{"duration":"562s","distanceMeters":2345}],"directionsUri":"https://www.google.com/maps/dir/-33.8688,151.1957362/''/data=!4m6!4m5!1m0!1m2!1m1!1s0x6b12ae3da97f60c1:0x845f3273bd764f6c!3e0"},…]}
Trong ví dụ này, bạn có thể thấy thời lượng và khoảng cách từ điểm bắt đầu định tuyến đến vị trí đầu tiên trong kết quả là 597 giây và 2.607 mét.
Sử dụng tính năng Tìm kiếm lân cận
Trong ví dụ này, bạn sẽ tính toán thời gian và khoảng cách di chuyển đến từng địa điểm trong phản hồi Tìm kiếm lân cận. Ví dụ này tìm kiếm các nhà hàng ở Sydney, Úc và đặt chế độ hạn chế về vị trí cũng như điểm xuất phát của tuyến đường thành cùng một toạ độ vĩ độ và kinh độ:
Bạn không cần phải sử dụng cùng một toạ độ cho locationRestriction và cho điểm bắt đầu định tuyến. Ví dụ: bạn đặt locationRestriction ở tâm của Sydney để điều chỉnh kết quả tìm kiếm theo vòng tròn đó. Nhưng sau đó, bạn đặt điểm bắt đầu chỉ đường thành toạ độ nhà mình, tức là một vị trí khác trong vòng tròn tìm kiếm. Sau đó, yêu cầu này sẽ điều chỉnh kết quả tìm kiếm cho phù hợp với vòng tròn và tính toán thông tin tóm tắt về việc định tuyến dựa trên vị trí nhà của bạn.
Chỉ định các lựa chọn di chuyển
Theo mặc định, các phép tính về thời lượng và khoảng cách là dành cho ô tô. Tuy nhiên, bạn có thể kiểm soát loại xe cũng như các lựa chọn khác trong quá trình tìm kiếm.
Sử dụng tham số routingParameters.travelMode để đặt chế độ di chuyển thành DRIVE, BICYCLE, WALK hoặc TWO_WHEELER. Để biết thêm thông tin về các lựa chọn này, hãy xem phần Các loại xe có thể dùng cho tuyến đường.
Sử dụng thuộc tính routingParameters.routingPreference để đặt lựa chọn ưu tiên về định tuyến thành TRAFFIC_UNAWARE (mặc định), TRAFFIC_AWARE hoặc TRAFFIC_AWARE_OPTIMAL. Mỗi lựa chọn có mức độ chất lượng dữ liệu và độ trễ khác nhau. Để biết thêm thông tin, hãy xem phần Chỉ định cách thức và việc có nên thêm dữ liệu lưu lượng truy cập hay không.
Thuộc tính routingParameters.routingPreference có ảnh hưởng đến các chỉ dẫn có trong trường Xem trước (Pre-GA) directionsUri vì Google Maps hiển thị các lựa chọn về giao thông khi mở đường liên kết.
Sử dụng thuộc tính routingParameters.routeModifiers để chỉ định avoidTolls, avoidHighways, avoidFerries và avoidIndoor. Để biết thêm thông tin về các lựa chọn này, hãy xem bài viết Chỉ định các đặc điểm của tuyến đường cần tránh.
Trong ví dụ tiếp theo, bạn chỉ định chế độ di chuyển là DRIVE và tránh đường cao tốc:
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 2025-09-05 UTC."],[[["\u003cp\u003eCalculate travel duration and distance to places returned by Text Search (New) or Nearby Search (New) by specifying the \u003ccode\u003eroutingParameters.origin\u003c/code\u003e and including \u003ccode\u003eroutingSummaries\u003c/code\u003e in the field mask.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eroutingSummaries\u003c/code\u003e array contains duration and distance from the origin to each place, mirroring the order of the \u003ccode\u003eplaces\u003c/code\u003e array.\u003c/p\u003e\n"],["\u003cp\u003eCustomize routing calculations by using \u003ccode\u003eroutingParameters\u003c/code\u003e to set travel mode (DRIVE, BICYCLE, WALK, TWO_WHEELER), routing preference (TRAFFIC_UNAWARE, TRAFFIC_AWARE, TRAFFIC_AWARE_OPTIMAL), and route modifiers (avoidTolls, avoidHighways, avoidFerries, avoidIndoor).\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003edirectionsUri\u003c/code\u003e field in the \u003ccode\u003eroutingSummaries\u003c/code\u003e (Preview, Pre-GA) provides a link to Google Maps directions for each place, using the specified routing parameters.\u003c/p\u003e\n"]]],[],null,["Calculate routing summary\n=========================\n\nTo use [Text Search (New)](/maps/documentation/places/web-service/text-search) or [Nearby Search (New)](/maps/documentation/places/web-service/nearby-search)\nto calculate the travel duration and distance to each place in the response:\n\n1. Pass the `routingParameters.origin` parameter in the request to specify the\n latitude and longitude coordinates of the routing origin. This parameter is\n required to calculate the duration and distance to each place in the\n response.\n\n2. Include `routingSummaries` in the field mask so that the response includes\n the `routingSummaries` array. This array contains the duration and distance\n from the routing origin to each place in the response.\n\n | **Note:** Adding `routingSummaries` in the field mask without also including either the `routingParameters.origin` parameter or the `searchAlongRouteParameters.polyline.encodedPolyline` parameter in the request causes an error.\n\nThe APIs Explorer lets you make live requests so that you can get familiar with\nthe API and the API options: \n[Try it!](#try_it)\n\nUse Text Search (New)\n---------------------\n\nIn the following request, you calculate the travel duration and distance to each\nplace in the Text Search (New) response: \n\n```scdoc\ncurl -X POST -d '{\n \"textQuery\" : \"Spicy Vegetarian Food in Sydney, Australia\",\n \"routingParameters\": {\n \"origin\": {\n \"latitude\": -33.8688,\n \"longitude\": 151.1957362\n }\n }\n}' \\\n-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \\\n-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel,routingSummaries' \\\n'https://places.googleapis.com/v1/places:searchText'\n```\n\nThe response contains two JSON arrays: the `places` array contains the matching\nplaces, and the `routingSummaries` array containing the duration and distance to\ntravel to each place: \n\n```yaml\n{\n \"places\": [\n {\n object (/maps/documentation/places/web-service/reference/rest/v1/places)\n }\n ]\n \"routingSummaries\": [\n {\n object (/maps/documentation/places/web-service/reference/rest/v1/RoutingSummary)\n }\n}\n```\n\nEach element in the `routingSummaries` array is at the corresponding array\nlocation as the place in the `places` array. That is, the element at\n`routingSummaries[0]` corresponds to the place at `places[0]`.\n\nThe array length of `routingSummaries` is the same as the array length of\n`places`. In the case where the `routingSummary` for a place is not available,\nthe array entry is empty.\n\nBecause this example calculates the duration and distance from the routing\norigin to each place, the `routingSummaries.legs` field in the response contains a single\n`Leg` object that contains the `duration` and `distanceMeters` from\nthe routing origin to the place.\n| **Note:** This response also includes the Preview (pre-GA) `directionsUri` field in the routing summary for each place. This field contains a link to open directions to the place in Google Maps. The `routingParameters.origin` parameter is used as the directions origin, the place location is used as the destination, and the travel mode defaults to drive.\n| This product or feature is in Preview (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the [Google\n| Maps Platform Service Specific Terms](https://cloud.google.com/maps-platform/terms/maps-service-terms). For more information, see the [launch stage\ndescriptions](/maps/launch-stages). \n\n```json\n{\n \"places\": [\n {\n \"formattedAddress\": \"1, Westfield Sydney Central Plaza, 450 George St, Sydney NSW 2000, Australia\",\n \"displayName\": {\n \"text\": \"Gözleme King Sydney\",\n \"languageCode\": \"en\"\n }\n },\n {\n \"formattedAddress\": \"367 Pitt St, Sydney NSW 2000, Australia\",\n \"priceLevel\": \"PRICE_LEVEL_MODERATE\",\n \"displayName\": {\n \"text\": \"Mother Chu's Vegetarian Kitchen\",\n \"languageCode\": \"en\"\n }\n },\n ...\n ]\n \"routingSummaries\": [\n {\n \"legs\": [\n {\n \"duration\": \"597s\",\n \"distanceMeters\": 2607\n }\n ],\n \"directionsUri\": \"https://www.google.com/maps/dir/-33.8688,151.1957362/''/data=!4m6!4m5!1m0!1m2!1m1!1s0x6b12ae3fa97cd745:0x6aecf365bf497c08!3e0\"\n },\n {\n \"legs\": [\n {\n \"duration\": \"562s\",\n \"distanceMeters\": 2345\n }\n ],\n \"directionsUri\": \"https://www.google.com/maps/dir/-33.8688,151.1957362/''/data=!4m6!4m5!1m0!1m2!1m1!1s0x6b12ae3da97f60c1:0x845f3273bd764f6c!3e0\"\n },\n ...\n ]\n}\n```\n\nFrom this example, you can see that the duration and distance from the routing\norigin to the first place in the results is 597 seconds and 2607 meters.\n\nUse Nearby Search\n-----------------\n\nIn this example, you calculate the travel duration and distance to each place in\nthe Nearby Search response. This example searches for restaurants in Sydney,\nAustralia and sets the location restriction and the routing origin to the same\nlatitude and longitude coordinate: \n\n```scdoc\n curl -X POST -d '{\n \"includedTypes\": [\"restaurant\"],\n \"maxResultCount\": 10,\n \"locationRestriction\": {\n \"circle\": {\n \"center\": {\n \"latitude\": -33.8688,\n \"longitude\": 151.1957362},\n \"radius\": 500.0\n }\n },\n \"routingParameters\": {\n \"origin\": {\n \"latitude\": -33.8688,\n \"longitude\": 151.1957362\n }\n }\n }' \\\n -H 'Content-Type: application/json' -H \"X-Goog-Api-Key:API_KEY\" \\\n -H \"X-Goog-FieldMask: places.displayName,routingSummaries\" \\\n https://places.googleapis.com/v1/places:searchNearby\n```\n\nYou don't have to use the same coordinates for the `locationRestriction` and the\nfor routing origin. For example, you set the `locationRestriction` to the center\npoint of Sydney to bias the search results to that circle. But you then set the\nrouting origin to the coordinates of your house, meaning to a different location\nwithin the search circle. The request then biases the search results to the\ncircle, and calculates the routing summaries based on the location of your\nhouse.\n\nSpecify travel options\n----------------------\n\nBy default, the duration and distance calculations are for a car. However, you\ncan control the vehicle type, as well as other options, in the search.\n\n- Use the `routingParameters.travelMode` parameter to set the mode of\n transportation to `DRIVE`, `BICYCLE`, `WALK`, or `TWO_WHEELER`. For more\n information on these options, see [Available vehicle types for\n routes](/maps/documentation/routes/vehicles).\n\n | **Note:** The Routes API also supports a mode of `TRANSIT`, but that mode is not supported by the Places API.\n | **Note:** The `TWO_WHEELER` option is only supported in those countries listed at [Countries and regions supported for two-wheeled\n | vehicles](/maps/documentation/routes/coverage-two-wheeled).\n- Use the `routingParameters.routingPreference` property to set the routing preference option to `TRAFFIC_UNAWARE` (default), `TRAFFIC_AWARE`, or `TRAFFIC_AWARE_OPTIMAL`. Each option has varying levels of data quality and latency. For more information, see [Specify how and if to include traffic\n data](/maps/documentation/routes/config_trade_offs).\n\n The `routingParameters.routingPreference` property does affect the\n directions contained in the Preview (Pre-GA) `directionsUri` field because\n Google Maps displays traffic options when it opens the link.\n- Use the `routingParameters.routeModifiers` property to specify to `avoidTolls`, `avoidHighways`, `avoidFerries`, and `avoidIndoor`. For more information on these options, see [Specify route features to\n avoid](/maps/documentation/routes/route-modifiers).\n\nIn the next example, you specify the travel mode as `DRIVE` and to avoid\nhighways: \n\n```scdoc\ncurl -X POST -d '{\n \"textQuery\" : \"Spicy Vegetarian Food in Sydney, Australia\",\n \"routingParameters\": {\n \"origin\": {\n \"latitude\": -33.8688,\n \"longitude\": 151.1957362\n },\n \"travelMode\":\"DRIVE\",\n \"routeModifiers\": {\n \"avoidHighways\": true\n }\n }\n}' \\\n-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \\\n-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel,routingSummaries' \\\n'https://places.googleapis.com/v1/places:searchText'\n```\n\nTry it!\n-------\n\nThe APIs Explorer lets you make sample requests so\nthat you can get familiar with the API and the API options.\n\n1. Select the API icon api\n on the right side of the page.\n\n2. Optionally edit the request parameters.\n\n3. Select the **Execute** button. In the dialog, choose the account\n that you want to use to make the request.\n\n4. In the APIs Explorer panel, select the fullscreen icon\n fullscreen to expand the APIs Explorer window."]]
