Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Как запросить ломаные линии маршрута

Разработчики из Европейской экономической зоны (ЕЭЗ)

Метод computeRoutes (REST) и метод ComputeRoutes (gRPC) возвращают маршрут, представленный в виде ломаной линии, как часть ответа. Эти API возвращают два типа ломаных линий:

Базовая ломаная линия (по умолчанию) представляет маршрут без информации о дорожном движении. Запросы, возвращающие базовую ломаную линию, оплачиваются по тарифу Routes Basic. Подробнее об оплате Routes API…
Ломаная линия с учетом загруженности дорог содержит информацию о загруженности дорог на маршруте. Загруженность дорог выражается в категориях скорости (NORMAL, SLOW, TRAFFIC_JAM), применимых к определенному интервалу полилинии. Запросы полилиний с учетом трафика оплачиваются по тарифу "Предпочтительные маршруты". Подробнее об оплате Routes API… Подробнее о том, как настроить качество полилинии…

Дополнительную информацию о ломаных линиях можно найти в следующих статьях:

Общие сведения о ломаных линиях
Интерактивная программа кодировки ломаных линий позволяет создавать кодированные ломаные линии в интерфейсе или декодировать ломаные линии для отображения на карте. Например, с помощью этой утилиты можно декодировать ломаную линию, созданную кодом ниже.

Примечание. Специальные символы в полилиниях, возвращаемых REST API, экранируются с помощью JSON. Чтобы показать эти ломаные линии в интерактивной программе кодировки ломаных линий, сначала нужно отменить экранирование. Существует множество утилит для декодирования JSON, например Freeformatter

Как запросить базовую ломаную линию для маршрута, этапа или шага

Ломаная линия представлена объектом Polyline (REST) или Polyline (gRPC). Вы можете вернуть ломаную линию в ответе на уровне маршрута, этапа и шага.

Укажите, какую ломаную линию нужно вернуть, с помощью маски поля ответа:

На уровне маршрута возвращайте в ответе ломаную линию, добавив routes.polyline в маску поля ответа.
На уровне сегмента возвращайте в ответе полилинию для каждого сегмента маршрута, добавив параметр routes.legs.polyline.

Примечание. Каждый этап соответствует поездке между двумя путевыми точками, если для путевой точки задано значение false в поле via, чтобы указать остановку на маршруте. Например, маршрут без промежуточных путевых точек состоит только из одного этапа. Маршрут, включающий промежуточную путевую точку с остановкой, состоит из двух отрезков. Маршрут, включающий одну промежуточную путевую точку со значением via, равным true, состоит из одного отрезка.
На уровне шага возвращайте в ответе ломаную линию для каждого шага маршрута, добавив параметр 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();