Эта страница переведена с помощью Cloud Translation API.

Запрос полилиний маршрута

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

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

Подробнее о полилиниях см.:

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

Запрос базовой полилинии для маршрута, участка или шага

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

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

На уровне маршрута верните в ответ ломаную линию, включив routes.polyline в маску поля ответа.
На уровне участка верните ломаную линию в ответе для каждого участка маршрута, включив в него routes.legs.polyline .
Примечание. Каждый этап соответствует поездке между двумя путевыми точками, если 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

Мы рекомендуем отображать на карте полилинии с учетом трафика, используя различные функции, предлагаемые SDK Google Maps, включая пользовательскую раскраску, обводку и узоры на участках полилинии. Дополнительные сведения об использовании полилиний см. в разделах «Функции полилиний для Android» и «Функции полилиний для iOS» .

Пример рендеринга полилинии

Пользователи Maps SDK имеют возможность определять собственную логику сопоставления между категориями скорости и схемами рендеринга полилиний. Например, можно решить отображать «НОРМАЛЬНУЮ» скорость на карте в виде толстой синей линии, а «МЕДЛЕННУЮ» скорость можно отображать, например, в виде толстой оранжевой линии.

В следующих фрагментах добавляется толстая синяя ломаная линия с геодезическими сегментами от Мельбурна до Перта. Дополнительные сведения см. в разделах Настройка внешнего вида (для Android) и Настройка полилинии (для iOS).

Андроид

Ява

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));

Котлин

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

Цель-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;

Быстрый

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