Sprawdź odpowiedź na trasę

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

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 pojazdu. Konfigurowanie tras przyjaznych dla środowiska
maksymalnie 3 trasy alternatywne. Prośba o trasy alternatywne
Polilinia całej trasy, każdego etapu trasy i każdego kroku etapu. Wymagania dotyczące ścieżek tras
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ą
Zlokalizowane odpowiedzi według kodów języka i jednostki miary (imperialnej lub metrycznej). Prośba o zlokalizowane wartości
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.

Informacje o maskach pól

Gdy wywołujesz metodę obliczania trasy, musisz określić maskę pola określającą pola, które mają być zwracane 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

Podczas wyświetlania wyników użytkownikom musisz dołączyć 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:

trasy, odcinka i kroku.

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 co najmniej jednego etapu.

  • 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 oddzielny odcinek ścieżki od każdego punktu pośredniego do kolejnego. Jeśli np. trasa zawiera jeden punkt początkowy i jeden punkt docelowy, składa się z jednego etapu. 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 punktach pośrednich znajdziesz w artykule Definiowanie pośredniego punktu pośredniego.

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

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 trasa 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 długości i szerokości geograficznej 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 jedną trasę, tzw. 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ć wartość parametru 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 Identyfikuje trasę domyślną.
FUEL_EFFICIENT Określa trasę przyjazną dla środowiska.
DEFAULT_ROUTE_ALTERNATE I wskazuje alternatywną trasę.

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. Każdy etap w tablicy określa ścieżkę z jednego punktu do następnego punktu na trasie. Trasa zawsze zawiera co najmniej 1 etap.

Właściwość legs zawiera definicję każdego kroku na 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 odpowiedzi zawiera tablicę steps, w której każdy element tablicy steps jest typu RouteLegStep. Krok odpowiada pojedynczej instrukcji w ramach danej nogi. Odcinek zawsze zawiera co najmniej 1 krok.

Każdy element w 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 języku lokalnym, transliterację na skrypt, który w razie potrzeby może odczytać użytkownik, z zachowaniem preferowanego języka. Komponenty 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 podanym języku, interfejs API używa najbliższego dopasowania.

  • 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.

Interpretowanie 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.

Tablica geocodingResults zawiera trzy pola:

  • origin: jeśli został podany jako ciąg adresu lub kod Plus, identyfikator miejsca punktu początkowego. W przeciwnym razie to pole jest pomijane w odpowiedzi.

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

  • intermediates: tablica zawierająca identyfikator miejsca pośrednich punktów pośrednich określonych w postaci ciągu adresu lub kodu Plus. Jeśli określisz pośredni punkt pośredni przy użyciu identyfikatora miejsca lub współrzędnych szerokości i długości geograficznej, 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.

"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 na przykład określisz kod języka niemiecki (de) i jednostki imperialne, wartość distanceMeters wyniesie 49889,7, ale otrzymasz też tekst z lokalizacją, który podaje tę odległość w jednostkach niemieckich i imperialnych, czyli „31 mil”.

Oto przykład wartości zlokalizowanych:

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

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 określa język en-US i jednostki IMPERIAL.
  • Metoda ComputeRouteMatrix domyślnie używa języka „en-US” i jednostek metrycznych.