Методы computeRoutes (REST) и ComputeRoutes (gRPC) возвращают маршрут, представленный ломаной линией, в составе ответа. Эти API возвращают два типа ломаных линий:
Базовая ломаная линия (по умолчанию) представляет маршрут без информации о дорожном движении. Запросы, возвращающие базовую ломаную линию, оплачиваются по тарифу Routes Basic. Подробнее об оплате Routes API…
Ломаная линия с учетом загруженности дорог содержит информацию о загруженности дорог на маршруте. Загруженность дорог выражается в категориях скорости (
NORMAL,SLOW,TRAFFIC_JAM), применимых к заданному интервалу ломаной линии. Запросы полилиний с учетом загруженности дорог оплачиваются по тарифу Routes Preferred. Подробнее об оплате Routes API… Подробнее о том, как настроить качество ломаной линии…
Дополнительную информацию о ломаных линиях можно найти в следующих статьях:
Интерактивная программа кодировки ломаных линий позволяет создавать кодированные ломаные линии в пользовательском интерфейсе или декодировать их для отображения на карте. Например, с помощью этой утилиты можно декодировать ломаную линию, созданную кодом ниже.
Как запросить базовую ломаную линию для маршрута, этапа или шага
Ломаная линия представлена объектом Polyline (REST) или Polyline (gRPC). Вы можете вернуть ломаную линию в ответе на уровне маршрута, этапа и шага.
Укажите, какую ломаную линию нужно вернуть, с помощью маски поля ответа:
На уровне маршрута возвращается ломаная линия в ответе, если в маску поля ответа включено значение
routes.polyline.На уровне этапа – возвращает ломаную линию в ответе для каждого этапа маршрута, если включен параметр
routes.legs.polyline.На уровне шага – возвращать в ответе ломаную линию для каждого шага этапа, включив
routes.legs.steps.polyline.
Например, чтобы получить ломаную линию для всего маршрута, для каждого этапа и для каждого шага каждого этапа:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Этот запрос возвращает следующий ответ, который включает ломаную линию для маршрута, для каждого этапа маршрута и для каждого шага этапа:
{ "routes": [ { "legs": [ { "polyline": { "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?" } }, "steps": [ { "polyline": { "encodedPolyline": "kclcF...@sC@YIOKI" } }, { "polyline": { "encodedPolyline": "wblcF~...SZSF_@?" } }, ... ], "distanceMeters": 56901, "duration": "2420s", "polyline": { "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?" } } ] }
Поскольку в запросе указаны только начальная и конечная точки, возвращенный маршрут содержит только один отрезок. Поэтому ломаная линия для этапа и маршрута будет одинаковой.
Если вы добавите в запрос промежуточную путевую точку, возвращенный маршрут будет содержать два этапа:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "intermediates": [ { "address": "450 Serra Mall, Stanford, CA 94305, USA"}, ], "travelMode": "DRIVE", }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Этот запрос возвращает два этапа, каждый со своей ломаной линией, и ломаную линию для всего маршрута:
{ "routes": [ { "legs": [ { "polyline": { "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG" } "steps": [ { "polyline": { "encodedPolyline": "kclcFfqch...YIOKI" } }, ... }, { "polyline": { "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G" } "steps": [ { "polyline": { "encodedPolyline": "uypeFbo`jVgJq...PoBiC" } }, ... } ], "distanceMeters": 68403, "duration": "3759s", "polyline": { "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE" } } ] }
Качество ломаной линии
Качество ломаной линии можно описать следующими терминами:
Точность записи с плавающей запятой для точек
Точки задаются значениями широты и долготы, которые представлены в формате с плавающей запятой одинарной точности. Это хорошо работает для небольших значений (которые могут быть представлены точно), но точность уменьшается по мере увеличения значений из-за ошибок округления с плавающей запятой.
В методах computeRoutes (REST) и ComputeRoutes это контролируется параметром
polylineEncoding.Количество точек, из которых состоит ломаная линия
Чем больше точек, тем более плавной будет ломаная линия (особенно на изгибах).
В методах computeRoutes (REST) и ComputeRoutes это контролируется параметром
polylineQuality.
Как настроить тип кодирования ломаных линий
Чтобы управлять типом ломаной линии, используйте параметр запроса polylineEncoding. Свойство polylineEncoding определяет, будет ли ломаная линия закодирована как ENCODED_POLYLINE (по умолчанию), то есть будет использоваться формат алгоритма закодированной ломаной линии, или как GEO_JSON_LINESTRING, то есть будет использоваться формат GeoJSON LineString.
Например, в теле запроса:
curl -X POST -d '{ "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE", "polylineEncoding": "ENCODED_POLYLINE" }' \ -H 'Content-Type: application/json' \ -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \ 'https://routes.googleapis.com/directions/v2:computeRoutes'
Настройка качества ломаной линии
polylineQuality определяет качество ломаной линии как HIGH_QUALITY или OVERVIEW (по умолчанию). При использовании OVERVIEW ломаная линия состоит из небольшого количества точек, а задержка запроса меньше, чем при использовании HIGH_QUALITY.
Например, в теле запроса:
{ "origin":{ "location":{ "latLng":{ "latitude": 37.419734, "longitude": -122.0827784 } } }, "destination":{ "location":{ "latLng":{ "latitude": 37.417670, "longitude": -122.079595 } } }, "travelMode": "DRIVE", "routingPreference": "TRAFFIC_AWARE", "polylineQuality": "HIGH_QUALITY", "polylineEncoding": "ENCODED_POLYLINE", "departureTime": "2023-10-15T15:01:23.045123456Z", ... }
Как запросить ломаную линию с учетом трафика
В приведенных выше примерах возвращаются базовые ломаные линии, то есть без информации о трафике. Кроме того, вы можете запросить, чтобы ломаная линия содержала информацию о дорожном движении для маршрута и каждого его участка.
Полилинии с учетом трафика содержат информацию о загруженности дорог на маршруте. Загруженность дорог выражается в категориях скорости (NORMAL, SLOW, TRAFFIC_JAM) для заданного интервала ломаной линии в ответе.
Интервалы определяются индексами начальной (включительно) и конечной (исключительно) точек ломаной линии.
Например, в следующем ответе показан трафик NORMAL между точками 2 и 4 ломаной линии:
{ "startPolylinePointIndex": 2, "endPolylinePointIndex": 4, "speed": "NORMAL" }
Чтобы запросить расчет ломаной линии с учетом трафика, задайте в запросе следующие свойства:
Чтобы включить расчет трафика, задайте для поля массива
extraComputationsзначениеTRAFFIC_ON_POLYLINE.Задайте для свойства
travelModeзначениеDRIVEилиTWO_WHEELER. Запросы для любого другого способа передвижения возвращают ошибку.Укажите в запросе предпочтительный маршрут:
TRAFFIC_AWAREилиTRAFFIC_AWARE_OPTIMAL. Подробнее о настройке качества и задержки…Задайте маску поля ответа, которая указывает, что нужно вернуть свойства ответа:
На уровне маршрута возвращаются все сведения о поездке, если в маске поля ответа указано
routes.travelAdvisory. Чтобы получить только информацию о трафике, укажитеroutes.travelAdvisory.speedReadingIntervals.На уровне этапа возвращает в ответе всю информацию о поездке для каждого этапа маршрута. Для этого нужно включить
routes.legs.travelAdvisory. Чтобы получить только информацию о загруженности дорог, укажитеroutes.legs.travelAdvisory.speedReadingIntervals.
curl -X POST -d '{
"origin":{
"address": "1600 Amphitheatre Parkway, Mountain View, CA"
},
"destination":{
"address": "24 Willie Mays Plaza, San Francisco, CA 94107"
},
"travelMode": "DRIVE",
"extraComputations": ["TRAFFIC_ON_POLYLINE"],
"routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \
'https://routes.googleapis.com/directions/v2:computeRoutes'Пример ответа для ломаной линии с учетом трафика
В ответе данные о трафике закодированы в ломаной линии и содержатся в поле travelAdvisory типа RouteLegTravelAdvisory (для каждого этапа) и RouteTravelAdvisory (для маршрута).
Пример:
{
"routes": [
{
"legs": {
"polyline": {
"encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
},
// Traffic data for the leg.
"travelAdvisory": {
"speedReadingIntervals": [
{
"endPolylinePointIndex": 1,
"speed": "NORMAL"
},
{
"startPolylinePointIndex": 1,
"endPolylinePointIndex": 2,
"speed": "SLOW"
},
{
"startPolylinePointIndex": 2,
"endPolylinePointIndex": 4,
"speed": "NORMAL"
}
]
}
},
"polyline": {
"encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
},
// Traffic data for the route.
"travelAdvisory": {
"speedReadingIntervals": [
{
"endPolylinePointIndex": 1,
"speed": "NORMAL"
},
{
"startPolylinePointIndex": 1,
"endPolylinePointIndex": 2,
"speed": "SLOW"
},
{
"startPolylinePointIndex": 2,
"endPolylinePointIndex": 4,
"speed": "NORMAL"
}
]
}
}
]
}
И RouteTravelAdvisory, и RouteLegTravelAdvisory включают поле массива speedReadingIntervals, которое содержит информацию о скорости движения. Каждый объект в массиве представлен объектом SpeedReadingInterval (REST) или SpeedReadingInterval (gRPC).
Объект SpeedReadingInterval содержит данные о скорости на интервале маршрута, например NORMAL, SLOW или TRAFFIC_JAM. Весь массив объектов покрывает всю ломаную линию маршрута без перекрытий. Начальная точка указанного интервала совпадает с конечной точкой предыдущего интервала.
Каждый интервал описывается значениями startPolylinePointIndex, endPolylinePointIndex и соответствующей категорией скорости. Обратите внимание, что отсутствие начального индекса в интервале соответствует индексу 0 в соответствии с практиками proto3.
Значения startPolylinePointIndex и endPolylinePointIndex не всегда идут подряд. Пример:
{
"startPolylinePointIndex": 2,
"endPolylinePointIndex": 4,
"speed": "NORMAL"
}
В этом случае загруженность дорог была одинаковой от индекса 2 до индекса 4.
Отрисовка ломаных линий с учетом трафика с помощью Maps SDK
Рекомендуем показывать на карте ломаные линии с учетом трафика, используя различные функции, предлагаемые Google Maps SDK, включая пользовательские цвета, штрихи и узоры вдоль отрезков ломаной линии. Подробнее о работе с ломаными линиями рассказывается в статьях Объекты ломаных линий для Android и Объекты ломаных линий для iOS.
Пример отрисовки ломаной линии
Пользователи Maps SDK могут задавать собственную логику сопоставления категорий скорости и схем отрисовки ломаных линий. Например, можно задать, чтобы участки с нормальной скоростью движения (NORMAL) отображались на карте толстой синей линией, а участки с низкой скоростью (SLOW) – толстой оранжевой линией.
Показанный ниже код соединяет Мельбурн и Перт толстой синей ломаной линией, сегменты которой являются геодезическими линиями Подробную информацию вы найдете в статьях Настройка внешнего вида (для Android) и Настройка ломаной линии (для iOS).
Android
Java
Polyline line = map.addPolyline(new PolylineOptions() .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734)) .width(25) .color(Color.BLUE) .geodesic(true));
Kotlin
val line: Polyline = map.addPolyline( PolylineOptions() .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734)) .width(25f) .color(Color.BLUE) .geodesic(true) )
iOS
Objective-C
GMSMutablePath *path = [GMSMutablePath path]; [path addLatitude:-37.81319 longitude:144.96298]; [path addLatitude:-31.95285 longitude:115.85734]; GMSPolyline *polyline = [GMSPolyline polylineWithPath:path]; polyline.strokeWidth = 10.f; polyline.strokeColor = .blue; polyline.geodesic = YES; polyline.map = mapView;
Swift
let path = GMSMutablePath() path.addLatitude(-37.81319, longitude: 144.96298) path.addLatitude(-31.95285, longitude: 115.85734) let polyline = GMSPolyline(path: path) polyline.strokeWidth = 10.0 polyline.geodesic = true polyline.map = mapView
Как использовать закодированные ломаные линии при поиске вдоль маршрута
Используйте новую версию текстового поиска в новой версии Places API, чтобы искать места вдоль рассчитанного маршрута. Вы передаете закодированную ломаную линию предварительно рассчитанного маршрута из Routes API Compute Routes в запрос текстового поиска (New). В ответе будут места, которые соответствуют критериям поиска и находятся рядом с указанным маршрутом. Подробнее о поиске вдоль маршрута…
Например, чтобы найти кафе вдоль маршрута между пунктами отправления и назначения, выполните следующие действия:
Node.js
const API_KEY = 'YOUR_API_KEY'; const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes'; const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';function init(){ const routes_request = { "origin":{ "address": "1600 Amphitheatre Parkway, Mountain View, CA" }, "destination":{ "address": "24 Willie Mays Plaza, San Francisco, CA 94107" }, "travelMode": "DRIVE" }; const textSearch_request = { "textQuery": "cafe", "searchAlongRouteParameters": { "polyline": { "encodedPolyline": "" } } }; fetchResources(routes_service,routes_request).then(routes => { textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline; fetchResources(textSearch_service,textSearch_request).then(places => { console.log(places); }); }); } async function fetchResources(resource,reqBody){ const response = await fetch(resource, { method: 'POST', body: JSON.stringify(reqBody), headers: { 'Content-Type': 'application/json', 'X-Goog-Api-Key': API_KEY, 'X-Goog-FieldMask': '*' } }); const responseJSON = await response.json(); return responseJSON; } init();