Sprawdź odpowiedź na trasę

Gdy interfejs Routes API oblicza trasę, przyjmuje jako dane wejściowe podane przez Ciebie punkty kontrolne i parametry konfiguracji. Interfejs API zwraca odpowiedź zawierającą domyślną trasę oraz co najmniej 1 alternatywną trasę.

Odpowiedź może zawierać różne typy tras i inne dane w zależności od pól, o które prosisz:

Aby uwzględnić to w odpowiedzi	Zobacz tę dokumentację
Trasa o największej paliwo- lub energooszczędności na podstawie typu silnika.	Konfigurowanie tras przyjaznych dla środowiska
maksymalnie 3 trasy alternatywne.	Prośba o trasy alternatywne
Polilinia dla całej trasy, dla każdego etapu trasy i dla każdego kroku etapu.	Wymagania dotyczące polilinii trasy
Szacowane opłaty za przejazd, uwzględniające wszelkie rabaty na opłaty za przejazd lub karty dostępne dla kierowcy lub pojazdu.	Obliczanie opłat za przejazd autostradą
odpowiedzi zlokalizowane według kodów języków i jednostek miary (imperialnych lub metrycznych);	Wysyłanie żądań z lokalizowanymi wartościami
Aby sformatować instrukcje nawigacji jako ciąg tekstowy HTML, dodaj HTML_FORMATTED_NAVIGATION_INSTRUCTIONS do extraComputations.	Dodatkowe obliczenia

Pełną listę opcji danych wejściowych znajdziesz w sekcji Dostępne opcje trasy i w ciele żądania.

Dzięki odpowiedzi możesz przekazać klientom informacje niezbędne do wybrania odpowiedniej trasy.

Uwaga: aby lepiej poznać sposób obsługi przez interfejs API różnych typów żądań trasy, wypróbuj wersję demonstracyjną. W wersji demonstracyjnej możesz wpisywać adresy, a potem wyświetlać odpowiedź w postaci wizualizacji.

Informacje o maskach pól

Gdy wywołujesz metodę obliczania trasy, musisz podać maskę pól, która określa, które pola mają być zwrócone w odpowiedzi. Nie ma domyślnej listy zwracanych pól. Jeśli pominiesz tę listę, metody zwrócą błąd.

Przykłady w tym dokumencie pokazują cały obiekt odpowiedzi bez uwzględniania masek pól. W środowisku produkcyjnym odpowiedź będzie zawierać tylko pola, które wyraźnie określisz w masce.

Więcej informacji znajdziesz w sekcji Wybieranie informacji do zwrócenia.

Wyświetlanie informacji o prawach autorskich

Wyświetlając wyniki użytkownikom, musisz uwzględnić to oświadczenie o prawach autorskich:

Powered by Google, ©YEAR Google

Na przykład:

Powered by Google, ©2023 Google

Informacje o trasach, odcinkach i krokach

Zanim przyjrzysz się odpowiedzi zwróconej przez interfejs Routes API, powinieneś zrozumieć komponenty, z których składa się trasa:

Odpowiedź może zawierać informacje o każdym z tych elementów trasy:

• Trasa: cała podróż od punktu docelowego do punktu początkowego, przez wszystkie punkty pośrednie. Trasa składa się z jednego lub większej liczby etapów.

• Etap: odcinek trasy od jednego punktu drogi do następnego. Każdy odcinek składa się z co najmniej 1 odrębnego etapu.

  Trasa zawiera osobny odcinek od jednego punktu pośredniego do następnego. Jeśli np. trasa zawiera 1 punkt kontrolny źródła i 1 punkt kontrolny celu, to zawiera 1 etap. Dla każdego dodatkowego punktu kontrolnego dodanego do trasy po punkcie początkowym i docelowym, zwanego punktem kontrolnym pośrednim, interfejs API dodaje osobny odcinek.

  Interfejs API nie dodaje etapu dla pośredniego punktu kontrolnego przelotnego. Na przykład trasa zawierająca punkt kontrolny miejsca wyjazdu, punkt kontrolny pośredni i punkt kontrolny miejsca docelowego zawiera tylko 1 odcinek z miejsca wyjazdu do miejsca docelowego, podczas gdy przechodzi przez punkt kontrolny. Więcej informacji o przekazywanych punktach drogi znajdziesz w artykule Definiowanie przekazywanego punktu drogi.

• Krok: pojedyncza instrukcja na odcinku trasy. Krok to najmniejsza jednostka trasy. Może to być na przykład „Skręć w lewo na ulicę Brzozowa”.

Co zawiera odpowiedź

Obiekt JSON reprezentujący odpowiedź interfejsu API zawiera te właściwości najwyższego poziomu:

• routes, tablica elementów typu Route. Tablica routes zawiera po jednym elemencie dla każdej trasy zwróconej przez interfejs API. Tablica może zawierać maksymalnie 5 elementów: trasę domyślną, trasę ekologiczną i maksymalnie 3 trasy alternatywne.

• geocodingResults, tablica elementów typu GeocodingResults. W przypadku każdej lokalizacji w żądaniu (początku, celu lub pośredniego punktu kontrolnego), która została określona jako ciąg znaków adresu lub jako kod plus, interfejs API wykonuje wyszukiwanie identyfikatora miejsca. Każdy element tej tablicy zawiera identyfikator miejsca docelowego odpowiadający lokalizacji. Lokalizacje w żądaniu określone jako identyfikator miejsca lub współrzędne geograficzne nie są uwzględniane. Jeśli wszystkie lokalizacje zostały określone za pomocą identyfikatorów miejsc lub współrzędnych geograficznych, tablica nie jest podawana.

• fallbackInfo typu FallbackInfo. Jeśli interfejs API nie może obliczyć trasy na podstawie wszystkich właściwości wejściowych, może użyć innego sposobu obliczeń. Gdy używany jest tryb awaryjny, to pole zawiera szczegółowe informacje o zastępczej odpowiedzi. W przeciwnym razie to pole nie jest skonfigurowane.

Odpowiedź ma postać:

{
  // The routes array.
  "routes": [
    {
      object (Route)
    }
  ],
  // The place ID lookup results.
  "geocodingResults": [
    {
      object (GeocodedWaypoint)
    }
  ],
  // The fallback property.
  "fallbackInfo": {
    object (FallbackInfo)
  }
}

Odczytywanie tablicy routes

Odpowiedź zawiera tablicę routes, w której każdy element ma typ Route. Każdy element tablicy reprezentuje całą trasę od miejsca wyjazdu do miejsca docelowego. Interfejs API zawsze zwraca co najmniej 1 trasę, zwaną trasą domyślną.

Możesz poprosić o dodatkowe trasy. Jeśli żądasz trasy przyjaznej dla środowiska, tablica może zawierać 2 elementy: trasę domyślną i trasę przyjazną dla środowiska. Możesz też ustawić parametr computeAlternativeRoutes na true w prośbie, aby dodać do odpowiedzi maksymalnie 3 alternatywne trasy.

Każda trasa w tablicy jest identyfikowana za pomocą właściwości tablicy routeLabels:

Wartość	Opis
DEFAULT_ROUTE	Określa trasę domyślną.
FUEL_EFFICIENT	Określa trasę ekologiczną.
DEFAULT_ROUTE_ALTERNATE	I wskazuje trasę alternatywną.

Tablica legs zawiera definicję każdego etapu trasy. Pozostałe właściwości, takie jak distanceMeters, duration i polyline,, zawierają informacje o trasie jako całości:

{
  "routeLabels": [
    enum (RouteLabel)
  ],
  "legs": [
    {
      object (RouteLeg)
    }
  ],
  "distanceMeters": integer,
  "duration": string,
  "routeLabels": [string],
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "description": string,
  "warnings": [
    string
  ],
  "viewport": {
    object (Viewport)
  },
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  }
  "routeToken": string
}

Ze względu na obecne warunki jazdy i inne czynniki trasa domyślna i przyjazna dla środowiska mogą być takie same. W tym przypadku tablica routeLabels zawiera obie etykiety: DEFAULT_ROUTE i FUEL_EFFICIENT.

{
  "routes": [
    {
      "routeLabels": [
        "DEFAULT_ROUTE",
        "FUEL_EFFICIENT"
      ],
     …
    }
  ]
}

Informacje o tablicy odcinków

Każdy element route w odpowiedzi zawiera tablicę legs, której każdy element jest typu RouteLeg.legs Każdy odcinek w tablicy definiuje ścieżkę od jednego punktu do następnego na trasie. Trasa zawsze zawiera co najmniej 1 etap.

Właściwość legs zawiera definicję każdego kroku w każdym etapie w tablicy steps. Pozostałe właściwości, takie jak distanceMeters, duration i polyline, zawierają informacje o odcinku.

{
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "steps": [
    {
      object (RouteLegStep)
    }
  ],
  "travelAdvisory": {
    object (RouteLegTravelAdvisory)
  }
}

Tablica kroków

Każdy etap w odpowiedzi zawiera tablicę steps, której każdy element jest typu RouteLegStep.steps Krok odpowiada pojedynczej instrukcji w ramach danego etapu. Odcinek zawsze zawiera co najmniej 1 krok.

Każdy element tablicy steps zawiera właściwość navigationInstruction typu NavigationInstruction, która zawiera instrukcję kroku. Na przykład:

"navigationInstruction": {
  "maneuver": "TURN_LEFT",
  "instructions": "Turn left toward Frontage Rd"
}

instructions może zawierać dodatkowe informacje o kroku. Przykład:

"navigationInstruction": {
  "maneuver": "TURN_SLIGHT_LEFT",
  "instructions": "Slight left (signs for I-90 W/Worcester)nParts of this road may be closed at certain times or days"
}

Pozostałe właściwości w kroku opisują informacje o kroku, takie jak distanceMeters, duration i polyline:

{
  "distanceMeters": integer,
  "staticDuration": string,
  "polyline": {
    object (Polyline)
  },
  "startLocation": {
    object (Location)
  },
  "endLocation": {
    object (Location)
  },
  "navigationInstruction": {
    object (NavigationInstruction)
  }
}

Określ język instrukcji

Interfejs API zwraca informacje o trasie w lokalnym języku, transliterowane do postaci czytelnej dla użytkownika, jeśli to konieczne, z uwzględnieniem preferowanego języka. Wszystkie elementy adresu są zwracane w tym samym języku.

• Użyj parametru languageCode w żądaniu, aby wyraźnie ustawić język trasy z listy obsługiwanych języków. Google często aktualizuje listę obsługiwanych języków, więc może ona nie być pełna.

• Jeśli nazwa nie jest dostępna w wybranym języku, interfejs API stosuje najbliższe dopasowanie.

• Wybrany język może mieć wpływ na zestaw wyników zwracanych przez interfejs API oraz na ich kolejność. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym. Na przykład utca i tér to synonimy słowa „ulica” w języku węgierskim.

Informacje o tablicy geocodingResults

W przypadku każdej lokalizacji w żądaniu (początku, celu lub punktu pośredniego) określonej jako ciąg znaków adresu lub kod Plus Code interfejs API próbuje znaleźć najbardziej odpowiednią lokalizację, która ma odpowiadający identyfikator miejsca. Każdy element tablicy geocodingResults zawiera pole placeID zawierające lokalizację w postaci identyfikatora miejsca oraz pole type określające typ lokalizacji, np. street_address, premise lub airport.

Uwaga: interfejs API nie uwzględnia w żądaniu lokalizacji określonych jako identyfikator miejsca lub współrzędne geograficzne. Jeśli wszystkie mają jeden z tych formatów, tablica nie jest przekazywana.

Tablica geocodingResults zawiera 3 pola:

• origin: jeśli podano go jako ciąg znaków adresu lub kod Plus Code, identyfikator miejsca pochodzenia. W przeciwnym razie to pole jest pomijane w odpowiedzi.

• destination: jeśli został podany jako ciąg znaków adresu lub kod plus, identyfikator miejsca docelowego. W przeciwnym razie to pole jest pomijane w odpowiedzi.

• intermediates: tablica zawierająca identyfikator miejsca dla wszystkich pośrednich punktów kontrolnych określonych jako ciąg znaków adresu lub kod Plus Code. Jeśli określisz punkt pośredni za pomocą identyfikatora miejsca lub współrzędnych geograficznych, zostanie on pominięty w odpowiedzi. Aby określić, który punkt pośredni w żądaniu odpowiada identyfikatorowi miejsca w odpowiedzi, użyj właściwości intermediateWaypointRequestIndex w odpowiedzi.

Uwaga: jeśli żądana lokalizacja nie istnieje lub nie można jej znaleźć, interfejs API nadal wypełnia tablicę geocodingResults w odpowiedzi. Tablica routes jest jednak pusta, ponieważ nie można obliczyć trasy do lokalizacji, której nie można znaleźć.

"geocodingResults": {
    "origin": {
        "geocoderStatus": {},
        "type": [
             enum (Type)
        ],
        "placeId": string
    },
    "destination": {
        "geocoderStatus": {},
        "type": [
            enum (Type)
        ],
        "placeId": string
    },
    "intermediates": [
        {
            "geocoderStatus": {},
            "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        },
        {
           "geocoderStatus": {},
           "intermediateWaypointRequestIndex": integer,
            "type": [
                enum (Type)
            ],
            "placeId": string
        }
    ]
}

Zrozumienie wartości odpowiedzi zlokalizowanych

Zlokalizowane wartości odpowiedzi to dodatkowe pole odpowiedzi, które zawiera zlokalizowany tekst zwracanych wartości parametrów. Tekst jest zlokalizowany w przypadku czasu trwania przejazdu, odległości i jednostek miary (metrycznych lub imperialnych). Wartości zlokalizowane są wysyłane za pomocą maski pola. Możesz określić język i system jednostek lub użyć wartości wywnioskowanych przez interfejs API. Więcej informacji znajdziesz w sekcji LocalizedValues.

Jeśli np.określisz kod języka niemiecki (de) i jednostki imperialne, wartość distanceMeters wyniesie 49889, 7, ale otrzymasz też zlokalizowany tekst podający tę miarę odległości w języku niemieckim i w jednostkach imperialnych, czyli „31 mil”.

Oto przykład zlokalizowanych wartości:

{ "localized_values":
  {
    "distance": { "text": "31,0 Meile/n" },
    "duration": { "text": 38 Minuten}.
    "static_duration": { "text": 36 Minuten}.
  }
}

Uwaga: możesz podać 2 wartości oczekiwanego czasu trwania: duration używa podanego przez Ciebie modelu ruchu, a static_duration nie uwzględnia ruchu. Jeśli więc żądany model natężenia ruchu to TRAFFIC_UNAWARE, te czasy są identyczne.

Jeśli nie określisz języka ani systemu jednostek, interfejs API wywnioskuje język i jednostki w ten sposób:

• Metoda ComputeRoutes określa lokalizację i odległość w jednostkach z punktu kontrolnego źródłowego. W przypadku żądania routingu w Stanach Zjednoczonych interfejs API wnioskuje o języku en-US i jednostkach IMPERIAL.
• Metoda ComputeRouteMatrix domyślnie używa języka „en-US” i jednostek metrycznych.