Method: computeRouteMatrix

Принимает список пунктов отправления и назначения и возвращает поток, содержащий информацию о маршруте для каждой комбинации пунктов отправления и назначения.

ПРИМЕЧАНИЕ: Этот метод требует указания маски поля ответа во входных данных. Маску поля ответа можно указать, используя параметр URL $fields или fields , либо используя HTTP/gRPC-заголовок X-Goog-FieldMask (см. доступные параметры URL и заголовки ). Значение представляет собой список путей к полям, разделенных запятыми. Подробнее о создании путей к полям см . в этой документации.

Например, в этом методе:

  • Маска поля всех доступных полей (для ручной проверки): X-Goog-FieldMask: *
  • Маска поля продолжительности маршрута, расстояния, статуса элемента, состояния и индексов элемента (пример производственной настройки): X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

Крайне важно включить status в маску поля, иначе все сообщения будут выглядеть корректно. Google не рекомендует использовать подстановочный знак ( * ) в маске поля ответа, поскольку:

  • Выбор только необходимых вам полей помогает нашему серверу экономить вычислительные циклы, что позволяет нам возвращать вам результат с меньшей задержкой.
  • Выбор только тех полей, которые вам необходимы в производственном задании, обеспечивает стабильную задержку. В будущем мы можем добавить дополнительные поля ответа, и для их обработки может потребоваться больше времени. Если вы выберете все поля или все поля на верхнем уровне, производительность может снизиться, поскольку любое новое поле, которое мы добавим, будет автоматически включено в ответ.
  • Выбор только необходимых полей приводит к уменьшению размера ответа и, следовательно, к повышению пропускной способности сети.

HTTP-запрос

POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

URL использует синтаксис перекодировки gRPC .

Текст запроса

Тело запроса содержит данные со следующей структурой:

JSON-представление 
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string,
  "arrivalTime": string,
  "languageCode": string,
  "regionCode": string,
  "units": enum (Units),
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "trafficModel": enum (TrafficModel),
  "transitPreferences": {
    object (TransitPreferences)
  }
}
Поля
origins[]

object ( RouteMatrixOrigin )

Обязательно. Массив исходных пунктов, определяющий строки матрицы ответов. На количество исходных пунктов и пунктов назначения накладывается ряд ограничений:

  • Сумма количества пунктов отправления + количества пунктов назначения, указанных как placeId или address не должна превышать 50.
  • Произведение количества пунктов отправления на количество пунктов назначения в любом случае не должно превышать 625.
  • Произведение количества пунктов отправления на количество пунктов назначения не должно превышать 100, если для параметра routingPreference установлено значение TRAFFIC_AWARE_OPTIMAL .
  • Произведение количества пунктов отправления на количество пунктов назначения не должно превышать 100, если для параметра travelMode установлено значение TRANSIT .
destinations[]

object ( RouteMatrixDestination )

Обязательно. Массив пунктов назначения, определяющий столбцы матрицы ответов.

travelMode

enum ( RouteTravelMode )

Необязательно. Указывает вид транспорта.

routingPreference

enum ( RoutingPreference )

Необязательный параметр. Указывает способ вычисления маршрута. Сервер пытается использовать выбранный параметр маршрутизации для вычисления маршрута. Если параметр маршрутизации приводит к ошибке или слишком большой задержке, возвращается ошибка. Этот параметр можно указать только в том случае, если travelMode — это DRIVE или TWO_WHEELER , в противном случае запрос не будет выполнен.

departureTime

string ( Timestamp format)

Необязательно. Время отправления. Если вы не укажете это значение, по умолчанию будет использоваться время, когда вы сделали запрос. ПРИМЕЧАНИЕ: departureTime можно указать только в прошлом, если для RouteTravelMode задано значение TRANSIT .

Использует RFC 3339, согласно которому сгенерированный вывод всегда будет нормализован по оси Z и содержать 0, 3, 6 или 9 знаков после запятой. Также допускаются смещения, отличные от «Z». Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

arrivalTime

string ( Timestamp format)

Необязательно. Время прибытия. ПРИМЕЧАНИЕ: Можно задать только если для RouteTravelMode задано значение TRANSIT . Можно указать либо departureTime , либо arrivalTime , но не оба.

Использует RFC 3339, согласно которому сгенерированный вывод всегда будет нормализован по оси Z и содержать 0, 3, 6 или 9 знаков после запятой. Также допускаются смещения, отличные от «Z». Примеры: "2014-10-02T15:01:23Z" , "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30" .

languageCode

string

Необязательно. Код языка BCP-47, например «en-US» или «sr-Latn». Подробнее см. в разделе «Идентификатор локали Unicode» . Список поддерживаемых языков см. в разделе «Поддержка языков». Если это значение не указано, язык отображения определяется на основе местоположения первого источника.

regionCode

string

Необязательно. Код региона, указанный как двухсимвольное значение ccTLD («домен верхнего уровня»). Подробнее см. в разделе Код страны для доменов верхнего уровня .

units

enum ( Units )

Необязательно. Указывает единицы измерения для отображаемых полей.

extraComputations[]

enum ( ExtraComputation )

Необязательно. Список дополнительных вычислений, которые могут быть использованы для выполнения запроса. Примечание: эти дополнительные вычисления могут возвращать дополнительные поля в ответе. Эти дополнительные поля также должны быть указаны в маске полей, чтобы быть возвращенными в ответе.

trafficModel

enum ( TrafficModel )

Необязательный параметр. Задаёт допущения, которые следует использовать при расчёте времени в пробках. Этот параметр влияет на значение, возвращаемое в поле продолжительности в RouteMatrixElement , которое содержит прогнозируемое время в пробках на основе исторических средних значений. TrafficModel доступен только для запросов, в которых для RoutingPreference задано значение TRAFFIC_AWARE_OPTIMAL , а для RouteTravelMode — значение DRIVE . По умолчанию используется значение BEST_GUESS , если запрашивается трафик, а TrafficModel не указан.

transitPreferences

object ( TransitPreferences )

Необязательно. Указывает настройки, влияющие на возвращаемый маршрут для маршрутов TRANSIT . ПРИМЕЧАНИЕ: transitPreferences можно указать только в том случае, если для RouteTravelMode задано значение TRANSIT .

Тело ответа

Содержит информацию о маршруте, рассчитанную для пары «отправитель/назначение» в API v2.computeRouteMatrix. Этот прототип может быть передан клиенту в потоковом режиме.

В случае успеха тело ответа содержит данные со следующей структурой:

JSON-представление 
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "localizedValues": {
    object (LocalizedValues)
  },
  "originIndex": integer,
  "destinationIndex": integer
}
Поля
status

object ( Status )

Код статуса ошибки для этого элемента.

condition

enum ( RouteMatrixElementCondition )

Показывает, найден ли маршрут. Независимо от статуса.

distanceMeters

integer

Пройденное расстояние маршрута в метрах.

duration

string ( Duration format)

Время, необходимое для прохождения маршрута. Если для routingPreference задано значение TRAFFIC_UNAWARE , это значение совпадает со значением staticDuration . Если для routingPreference задано значение TRAFFIC_AWARE или TRAFFIC_AWARE_OPTIMAL , это значение рассчитывается с учётом дорожной ситуации.

Длительность в секундах, содержащая до девяти знаков после запятой, заканчивается на « s ». Пример: "3.5s" .

staticDuration

string ( Duration format)

Продолжительность проезда по маршруту без учета дорожной обстановки.

Длительность в секундах, содержащая до девяти знаков после запятой, заканчивается на « s ». Пример: "3.5s" .

travelAdvisory

object ( RouteTravelAdvisory )

Дополнительная информация о маршруте. Например, информация об ограничениях и платных дорогах.

fallbackInfo

object ( FallbackInfo )

В некоторых случаях, когда сервер не может рассчитать маршрут с заданными настройками для данной пары «источник/назначение», он может использовать другой режим расчёта. При использовании резервного режима это поле содержит подробную информацию о резервном ответе. В противном случае это поле не заполнено.

localizedValues

object ( LocalizedValues )

Текстовые представления свойств RouteMatrixElement .

originIndex

integer

Нулевой индекс источника в запросе.

destinationIndex

integer

Индекс назначения в запросе (начиная с нуля).

RouteMatrixOrigin

Единый источник для ComputeRouteMatrixRequest

JSON-представление 
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
Поля
waypoint

object ( Waypoint )

Обязательно. Исходная точка маршрута

routeModifiers

object ( RouteModifiers )

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

RouteMatrixDestination

Единый пункт назначения для ComputeRouteMatrixRequest

JSON-представление 
{
  "waypoint": {
    object (Waypoint)
  }
}
Поля
waypoint

object ( Waypoint )

Обязательно. Пункт назначения.

ExtraComputation

При выполнении запроса необходимо выполнить дополнительные вычисления.

Перечисления
EXTRA_COMPUTATION_UNSPECIFIED Не используется. Запросы, содержащие это значение, не будут выполнены.
TOLLS Информация о плате за проезд для элемента(ов) матрицы.

RouteMatrixElementCondition

Состояние возвращаемого маршрута.

Перечисления
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED Используется только в том случае, если status элемента не ОК.
ROUTE_EXISTS Маршрут найден, и для элемента заполнена соответствующая информация.
ROUTE_NOT_FOUND Маршрут не найден. Поля, содержащие информацию о маршруте, например, distanceMeters или duration , не будут заполнены в элементе.

Локализованные значения

Текстовые представления определенных свойств.

JSON-представление 
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
Поля
distance

object ( LocalizedText )

Расстояние поездки представлено в текстовом виде.

duration

object ( LocalizedText )

Длительность представлена ​​в текстовом формате с учётом дорожной ситуации. Примечание: если информация о дорожной ситуации не запрашивалась, это значение совпадает со значением staticDuration.

staticDuration

object ( LocalizedText )

Продолжительность указана в текстовом виде без учета дорожной обстановки.

transitFare

object ( LocalizedText )

Стоимость проезда представлена ​​в текстовом виде.