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

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

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

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

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

Более подробную информацию о ломаных линиях см. в:

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

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

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

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

На уровне маршрута верните в ответе полилинию, включив routes.polyline в маску поля ответа.
На уровне отдельных участков маршрута верните в ответе полилинию для каждого участка маршрута, указав в качестве параметра routes.legs.polyline .
Примечание: Каждый участок маршрута соответствует пути между двумя промежуточными точками, если via имеет значение false, чтобы указать промежуточную точку на маршруте. Например, маршрут без промежуточных точек имеет только один участок. Маршрут, включающий промежуточную точку с остановкой, имеет два участка. Маршрут, включающий одну промежуточную точку, если параметр 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"
      }
    }
  ]
}

Качество Polyline

Качество полилинии можно описать следующими терминами:

Точность вычислений с плавающей запятой для точек
Точки задаются значениями широты и долготы, представленными в формате чисел с плавающей запятой одинарной точности. Это хорошо работает для малых значений (которые можно представить точно), но точность снижается по мере увеличения значений из-за ошибок округления чисел с плавающей запятой.
В методе computeRoutes (REST) и в ComputeRoutes это контролируется параметром polylineEncoding .
Количество точек, составляющих ломаную линию.
Чем больше точек, тем более плавной становится ломаная линия (особенно на кривых).
В методе computeRoutes (REST) и в самом методе ComputeRoutes это контролируется параметром polylineQuality .

Настройте тип кодирования полилинии

Для управления типом полилинии используйте параметр запроса polylineEncoding . Свойство polylineEncoding определяет, будет ли полилиния кодироваться как ENCODED_POLYLINE (по умолчанию), то есть будет использоваться формат Encoded Polyline Algorithm Format , или 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).

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

Котлин

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;

Быстрый

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 в запрос текстового поиска. В ответе будут содержаться места, соответствующие критериям поиска и расположенные рядом с указанным маршрутом. Подробнее см. поиск вдоль маршрута .

Например, чтобы вернуться в кафе, расположенные вдоль маршрута между пунктом отправления и пунктом назначения:

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