Method: computeRouteMatrix

Odbiera listę miejsc nadania i miejsc docelowych, a następnie zwraca strumień zawierający informacje o trasach dla każdej kombinacji miejsca nadania i miejsca docelowego.

UWAGA: ta metoda wymaga podania w danych wejściowych maski pola odpowiedzi. Możesz podać maskę pola odpowiedzi, używając parametru URL $fields lub fields albo nagłówka HTTP/gRPC X-Goog-FieldMask (patrz dostępne parametry i nagłówki URL). Wartość to lista ścieżek pól rozdzielona przecinkami. Zapoznaj się z szczegółową dokumentacją dotyczącą tworzenia ścieżek pól.

Na przykład w tej metodzie:

  • Maska pól wszystkich dostępnych pól (do ręcznej kontroli): X-Goog-FieldMask: *
  • Maska pola z czasami trwania trasy, odległościami, stanem i warunkami elementu oraz indeksami elementów (przykładowe ustawienie produkcyjne): X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

Ważne jest, aby w masce pola uwzględnić status, ponieważ w przeciwnym razie wszystkie wiadomości będą wyświetlane jako OK. Google nie zaleca używania maski pola odpowiedzi z symbolem wieloznacznym (*), ponieważ:

  • Wybranie tylko tych pól, których potrzebujesz, pomaga naszemu serwerowi oszczędzać cykle obliczeniowe, dzięki czemu możemy zwrócić Ci wynik z mniejszym opóźnieniem.
  • Wybranie tylko tych pól, których potrzebujesz w produkcyjnym zadaniu, zapewnia stabilną wartość opóźnienia. W przyszłości możemy dodać więcej pól odpowiedzi, a to może wydłużyć czas obliczeń. Jeśli wybierzesz wszystkie pola lub wszystkie pola na najwyższym poziomie, może to spowodować pogorszenie wydajności, ponieważ każde nowe pole, które dodamy, będzie automatycznie uwzględniane w odpowiedzi.
  • Wybranie tylko potrzebnych pól powoduje mniejszy rozmiar odpowiedzi, a co za tym idzie, większą przepustowość sieci.

Żądanie HTTP

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

Adres URL używa składni transkodowania gRPC.

Treść żądania

Treść żądania zawiera dane o następującej strukturze:

Zapis 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)
  }
}
Pola
origins[]

object (RouteMatrixOrigin)

Wymagane. Tablica źródeł, która określa wiersze macierzy odpowiedzi. Moc zbioru źródeł i miejsc docelowych podlega kilku ograniczeniom rozmiaru:

  • Suma liczby miejsc pochodzenia + liczba miejsc docelowych podanych jako placeId lub address nie może przekraczać 50.
  • Wynik mnożenia liczby miejsc pochodzenia x liczba miejsc docelowych nie może być większy niż 625.
  • Jeśli parametr routingPreference ma wartość TRAFFIC_AWARE_OPTIMAL, iloczyn liczby źródeł i liczby miejsc docelowych nie może być większy niż 100.
  • Jeśli parametr travelMode ma wartość TRANSIT, iloczyn liczby miejsc wylotu i liczba miejsc docelowych nie może być większy niż 100.
destinations[]

object (RouteMatrixDestination)

Wymagane. Tablica miejsc docelowych, która określa kolumny macierzy odpowiedzi.
travelMode

enum (RouteTravelMode)

Opcjonalnie. Określa środek transportu.
routingPreference

enum (RoutingPreference)

Opcjonalnie. Określa sposób obliczania trasy. Serwer próbuje użyć wybranych preferencji routingu do obliczenia trasy. Jeśli preferencja routingu powoduje błąd lub wydłuża czas oczekiwania, zwracany jest błąd. Możesz ustawić tę opcję tylko wtedy, gdy travelMode ma wartość DRIVE lub TWO_WHEELER. W przeciwnym razie żądanie się nie powiedzie.
departureTime

string (Timestamp format)

Opcjonalnie. Godzina wyjazdu. Jeśli nie ustawisz tej wartości, zostanie ona domyślnie zdefiniowana jako czas wysłania żądania. UWAGA: wartość departureTime możesz określić w przeszłości tylko wtedy, gdy ustawienie RouteTravelMode ma wartość TRANSIT.

Używa standardu RFC 3339, w którym wygenerowany wynik jest zawsze znormalizowany według normy Z i zawiera 0, 3, 6 lub 9 cyfr ułamkowych. Dopuszczalne są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".
arrivalTime

string (Timestamp format)

Opcjonalnie. Godzina przyjazdu. UWAGA: można ustawić tylko wtedy, gdy ustawienie RouteTravelMode ma wartość TRANSIT. Możesz podać wartość departureTime lub arrivalTime, ale nie obie.

Używa standardu RFC 3339, w którym wygenerowany wynik jest zawsze znormalizowany według normy Z i zawiera 0, 3, 6 lub 9 cyfr ułamkowych. Dopuszczalne są też przesunięcia inne niż „Z”. Przykłady: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" lub "2014-10-02T15:01:23+05:30".
languageCode

string

Opcjonalnie. Kod języka BCP-47, np. „pl-PL” lub „sr-Latn”. Więcej informacji znajdziesz w artykule Identyfikator języka w standardzie Unicode. Listę obsługiwanych języków znajdziesz w sekcji Obsługiwane języki. Jeśli nie podasz tej wartości, język wyświetlania zostanie wywnioskowany na podstawie lokalizacji pierwszego źródła.
regionCode

string

Opcjonalnie. Kod regionu podany jako 2-znakowa wartość domeny krajowej najwyższego poziomu. Więcej informacji znajdziesz w artykule Domena krajowa najwyższego poziomu.
units

enum (Units)

Opcjonalnie. Określa jednostki miary dla pól wyświetlania.
extraComputations[]

enum (ExtraComputation)

Opcjonalnie. Lista dodatkowych obliczeń, które mogą być użyte do wykonania żądania. Uwaga: te dodatkowe obliczenia mogą zwrócić dodatkowe pola w odpowiedzi. Te dodatkowe pola muszą też być określone w masce pola, aby mogły być zwracane w odpowiedzi.
trafficModel

enum (TrafficModel)

Opcjonalnie. Określa założenia stosowane podczas obliczania czasu w ruchu. To ustawienie wpływa na wartość zwracaną w polu duration w elementach RouteMatrixElement, które zawierają przewidywany czas w ruchu na podstawie średnich wartości historycznych. Opcja TrafficModel jest dostępna tylko w przypadku żądań, w których parametr RoutingPreference ma wartość TRAFFIC_AWARE_OPTIMAL, a parametr RouteTravelMode – wartość DRIVE. Jeśli żądany jest ruch, a wartość TrafficModel nie została podana, domyślnie przyjmuje się BEST_GUESS.
transitPreferences

object (TransitPreferences)

Opcjonalnie. Określa preferencje, które wpływają na trasę zwróconą dla tras TRANSIT. UWAGA: możesz określić wartość transitPreferences tylko wtedy, gdy ustawienie RouteTravelMode ma wartość TRANSIT.

Treść odpowiedzi

Zawiera informacje o trasie obliczonej dla pary źródlo/miejsce docelowe w interfejsie v2.computeRouteMatrix API. Protokół można przesyłać strumieniowo do klienta.

W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:

Zapis 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
}
Pola
status

object (Status)

Kod stanu błędu tego elementu.
condition

enum (RouteMatrixElementCondition)

Wskazuje, czy trasa została znaleziona. Niezależnie od stanu.
distanceMeters

integer

Odległość do przebycia na trasie w metrach.
duration

string (Duration format)

Czas potrzebny na przejechanie trasy. Jeśli ustawisz wartość routingPreference na TRAFFIC_UNAWARE, będzie ona taka sama jak wartość staticDuration. Jeśli ustawisz wartość routingPreference na TRAFFIC_AWARE lub TRAFFIC_AWARE_OPTIMAL, zostanie ona obliczona z uwzględnieniem warunków ruchu.

Czas w sekundach z maksymalnie 9 miejscami po przecinku, zakończony literą „s”. Przykład: "3.5s".
staticDuration

string (Duration format)

Czas przejazdu trasy bez uwzględnienia warunków na drodze.

Czas w sekundach z maksymalnie 9 miejscami po przecinku, zakończony literą „s”. Przykład: "3.5s".
travelAdvisory

object (RouteTravelAdvisory)

dodatkowe informacje o trasie. Na przykład: informacje o ograniczeniach i informacje o opłatach
fallbackInfo

object (FallbackInfo)

W niektórych przypadkach, gdy serwer nie może obliczyć trasy z uwzględnieniem podanych preferencji w przypadku danego połączenia między punktem początkowym a docelowym, może użyć innego trybu obliczeń. Gdy używany jest tryb zapasowy, to pole zawiera szczegółowe informacje o odpowiednich odpowiedziach. W przeciwnym razie to pole nie jest ustawione.
localizedValues

object (LocalizedValues)

Tekstowe reprezentacje właściwości obiektu RouteMatrixElement.
originIndex

integer

Źródło w żądaniu – indeks od 0.
destinationIndex

integer

Indeks miejsca docelowego w żądaniu liczony od zera.

RouteMatrixOrigin

Pojedyncze źródło dla ComputeRouteMatrixRequest

Zapis JSON 
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
Pola
waypoint

object (Waypoint)

Wymagane. Punkt początkowy
routeModifiers

object (RouteModifiers)

Opcjonalnie. Modyfikatory dla każdej trasy, która ma ten punkt jako punkt początkowy

RouteMatrixDestination

Pojedyncze miejsce docelowe dla ComputeRouteMatrixRequest

Zapis JSON 
{
  "waypoint": {
    object (Waypoint)
  }
}
Pola
waypoint

object (Waypoint)

Wymagane. Punkt docelowy

ExtraComputation

dodatkowe obliczenia do wykonania podczas realizacji prośby;

Wartości w polu enum
EXTRA_COMPUTATION_UNSPECIFIED Nieużywane. Żądania zawierające tę wartość nie zostaną zrealizowane.
TOLLS Informacje o opłatach za elementy macierzy.

RouteMatrixElementCondition

Stan zwracanej trasy.

Wartości w polu enum
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED Używana tylko wtedy, gdy status elementu nie jest OK.
ROUTE_EXISTS Trasa została znaleziona, a odpowiednie informacje zostały wypełnione w przypadku tego elementu.
ROUTE_NOT_FOUND Nie znaleziono trasy. Pola zawierające informacje o trasie, takie jak distanceMeters lub duration, nie będą wypełniane w elemencie.

LocalizedValues

tekstowe reprezentacje niektórych właściwości;

Zapis JSON 
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
Pola
distance

object (LocalizedText)

Odległość do pokonania w postaci tekstu.
duration

object (LocalizedText)

Czas trwania w formie tekstowej uwzględniający warunki ruchu. Uwaga: jeśli nie przesłano żądania informacji o ruchu, ta wartość jest taka sama jak staticDuration.
staticDuration

object (LocalizedText)

Czas trwania w postaci tekstu bez uwzględniania warunków ruchu.
transitFare

object (LocalizedText)

Opłata za przejazd w formie tekstu.