Method: computeRouteMatrix

Przyjmuje listę miejsc początkowych i docelowych oraz zwraca strumień zawierający informacje o trasie dla każdej kombinacji miejsca początkowego i docelowego.

UWAGA: ta metoda wymaga podania w danych wejściowych maski pola odpowiedzi. Maskę pola odpowiedzi możesz podać za pomocą parametru adresu URL $fields lub fields albo za pomocą nagłówka HTTP/gRPC X-Goog-FieldMask (zobacz dostępne parametry adresu URL i nagłówki). Wartość to lista ścieżek do pól rozdzielona przecinkami. Szczegółowe informacje o tworzeniu ścieżek pól znajdziesz w tej dokumentacji.

Na przykład w tej metodzie:

  • Maska pola wszystkich dostępnych pól (do ręcznego sprawdzenia): X-Goog-FieldMask: *
  • Maska pola czasu trwania trasy, odległości, stanu elementu, warunku i indeksów elementów (przykładowa konfiguracja produkcyjna): X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

Ważne jest, aby w masce pola umieścić znak status, ponieważ w przeciwnym razie wszystkie wiadomości będą wyglądać na prawidłowe. Google odradza używanie maski pola odpowiedzi z symbolem wieloznacznym (*), ponieważ:

  • Wybieranie tylko potrzebnych pól pomaga naszemu serwerowi oszczędzać cykle obliczeniowe, co pozwala nam zwracać wyniki z mniejszym opóźnieniem.
  • Wybieranie w zadaniu produkcyjnym tylko potrzebnych pól zapewnia stabilną wydajność w zakresie opóźnień. W przyszłości możemy dodać więcej pól odpowiedzi, a nowe pola mogą wymagać dodatkowego czasu obliczeniowego. Jeśli wybierzesz wszystkie pola lub wszystkie pola na najwyższym poziomie, może to spowodować spadek wydajności, ponieważ każde nowe pole, które dodamy, będzie automatycznie uwzględniane w odpowiedzi.
  • Wybieranie tylko potrzebnych pól powoduje zmniejszenie rozmiaru odpowiedzi, a tym samym zwiększenie przepustowości 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 punktów początkowych, która określa wiersze macierzy odpowiedzi. W przypadku mocy zbioru źródeł i miejsc docelowych obowiązuje kilka ograniczeń rozmiaru:

  • Suma liczby punktów początkowych i liczby punktów docelowych określonych jako placeId lub address nie może być większa niż 50.
  • Iloczyn liczby miejsc docelowych i miejsc pochodzenia nie może w żadnym przypadku przekraczać 625.
  • Jeśli parametr routingPreference ma wartość TRAFFIC_AWARE_OPTIMAL, iloczyn liczby punktów początkowych i liczby punktów docelowych nie może być większy niż 100.
  • Jeśli parametr travelMode ma wartość TRANSIT, iloczyn liczby punktów początkowych i liczby punktów 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 obliczyć trasę przy użyciu wybranego ustawienia routingu. Jeśli preferencja routingu spowoduje błąd lub wyjątkowo długie opóźnienie, zwracany jest błąd. Tę opcję możesz określić tylko wtedy, gdy travelMode ma wartość DRIVE lub TWO_WHEELER. W przeciwnym razie żądanie się nie powiedzie.
departureTime

string (Timestamp format)

Opcjonalnie: Godzina odjazdu. Jeśli nie ustawisz tej wartości, domyślnie będzie to czas wysłania żądania. UWAGA: datę departureTime w przeszłości możesz określić tylko wtedy, gdy ustawienie RouteTravelMode ma wartość TRANSIT.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane 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 określić wartość departureTime lub arrivalTime, ale nie obie jednocześnie.

Korzysta ze standardu RFC 3339, w którym wygenerowane dane wyjściowe są zawsze znormalizowane do formatu Z i zawierają 0, 3, 6 lub 9 cyfr po przecinku. Akceptowane 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 w formacie BCP-47, np. „en-US” lub „sr-Latn”. Więcej informacji znajdziesz w artykule Identyfikator ustawień regionalnych Unicode. Listę obsługiwanych języków znajdziesz w sekcji Obsługa języków. Jeśli nie podasz tej wartości, język wyświetlania zostanie określony na podstawie lokalizacji pierwszego źródła.
regionCode

string

Opcjonalnie: Kod regionu określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Więcej informacji znajdziesz w artykule Domeny krajowe 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 zrealizowania żądania. Uwaga: te dodatkowe obliczenia mogą zwracać dodatkowe pola w odpowiedzi. Te dodatkowe pola muszą być też określone w masce pola, aby były zwracane w odpowiedzi.
trafficModel

enum (TrafficModel)

Opcjonalnie: Określa założenia, które mają być używane podczas obliczania czasu w ruchu. To ustawienie wpływa na wartość zwracaną w polu czasu trwania w RouteMatrixElement, które zawiera przewidywany czas w ruchu na podstawie średnich wartości historycznych. TrafficModel jest dostępna tylko w przypadku żądań, w których parametr RoutingPreference ma wartość TRAFFIC_AWARE_OPTIMAL, a parametr RouteTravelMode ma wartość DRIVE. Jeśli wysyłane jest żądanie dotyczące ruchu, a wartość TrafficModel nie jest określona, domyślnie przyjmuje się wartość BEST_GUESS.
transitPreferences

object (TransitPreferences)

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

Treść odpowiedzi

Zawiera informacje o trasie obliczone dla pary punktów początkowego i docelowego w interfejsie v2.computeRouteMatrix API. Ten 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 pokonania na trasie w metrach.
duration

string (Duration format)

czas potrzebny na pokonanie trasy. Jeśli ustawisz wartość routingPreference na TRAFFIC_UNAWARE, ta wartość będzie taka sama jak staticDuration. Jeśli ustawisz routingPreference na TRAFFIC_AWARE lub TRAFFIC_AWARE_OPTIMAL, ta wartość zostanie obliczona z uwzględnieniem warunków drogowych.

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

string (Duration format)

Czas podróży po trasie bez uwzględniania warunków drogowych.

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

object (RouteTravelAdvisory)

Dodatkowe informacje o trasie. Na przykład informacje o ograniczeniach i opłatach za przejazd.
fallbackInfo

object (FallbackInfo)

W niektórych przypadkach, gdy serwer nie może obliczyć trasy z uwzględnieniem podanych preferencji dla danej pary punktów początkowego i docelowego, może użyć innego trybu obliczeń. Gdy używany jest tryb rezerwowy, to pole zawiera szczegółowe informacje o odpowiedzi rezerwowej. W przeciwnym razie to pole nie jest ustawione.
localizedValues

object (LocalizedValues)

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

integer

Indeks punktu początkowego w żądaniu liczony od zera.
destinationIndex

integer

Indeks miejsca docelowego w żądaniu liczony od zera.

RouteMatrixOrigin

Pojedyncze źródło w przypadku 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 to miejsce jako punkt początkowy

RouteMatrixDestination

Pojedyncze miejsce docelowe dla ComputeRouteMatrixRequest

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

object (Waypoint)

Wymagane. Docelowy punkt pośredni

ExtraComputation

Dodatkowe obliczenia do wykonania podczas realizacji prośby.

Wartości w polu enum
EXTRA_COMPUTATION_UNSPECIFIED Nie używane. Żądania zawierające tę wartość nie zostaną zrealizowane.
TOLLS Informacje o opłatach za przejazd dla elementów macierzy.

RouteMatrixElementCondition

Stan zwracanej trasy.

Wartości w polu enum
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED Używany tylko wtedy, gdy status elementu nie ma wartości OK.
ROUTE_EXISTS Znaleziono trasę i w elemencie uzupełniono odpowiednie informacje.
ROUTE_NOT_FOUND Nie udało się znaleźć trasy. Pola zawierające informacje o trasie, takie jak distanceMeters czy duration, nie zostaną wypełnione w elemencie.

LocalizedValues

Tekstowe reprezentacje niektórych usług.

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

object (LocalizedText)

Odległość podróży w formie tekstowej.
duration

object (LocalizedText)

Czas trwania w formie tekstowej z uwzględnieniem warunków drogowych. Uwaga: jeśli informacje o ruchu nie zostały przesłane w żądaniu, ta wartość jest taka sama jak staticDuration.
staticDuration

object (LocalizedText)

Czas trwania podany w formie tekstowej bez uwzględnienia warunków drogowych.
transitFare

object (LocalizedText)

Cena transportu publicznego w formie tekstowej.