Odpowiedź na pytania dotyczące tras obliczeniowych

Do obliczenia trasy interfejs Routes API wykorzystuje jako dane wejściowe listę punktów na trasie i parametry konfiguracji. Interfejs API zwraca odpowiedź zawierającą trasę default i co najmniej 1 trasę opcjonalną.

Żądanie obliczenia trasy obsługuje wiele opcji wprowadzania. Możesz na przykład przesłać taką prośbę:

  • Ekologiczna trasa z największą spalaniem lub energooszczędnością na podstawie typu silnika pojazdu.

  • maks. trzy trasy alternatywne;

  • Linia łamana obejmująca całą trasę, każdy etap trasy i każdy krok kroku.

  • Szacowane opłaty za przejazd, z uwzględnieniem wszelkich zniżek na drogi płatne dla kierowców lub pojazdów.

  • Wiele innych opcji. Pełną listę opcji wprowadzania znajdziesz w treści żądania.

Na podstawie odpowiedzi udzielisz klientom informacji niezbędnych do wyboru odpowiedniej trasy.

Maski pól

Gdy wywołujesz metodę wyznaczania trasy, musisz określić maskę pola, która określa pola, które mają być zwracane w odpowiedzi. Nie ma domyślnej listy zwróconych pól. Jeśli pominiesz tę listę, metody będą zwracać 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 wyraźnie określone w masce pól.

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

Informacje o wyświetlaniu praw autorskich

Podczas wyświetlania wyników użytkownikom musisz zamieścić poniższe oświadczenie dotyczące praw autorskich:

Powered by Google, ©YEAR Google

Na przykład:

Powered by Google, ©2023 Google

Informacje o trasach, nogach i krokach

Zanim sprawdzisz odpowiedź zwracaną przez interfejs Routes API, musisz wiedzieć, co składa się na trasę:

Trasa, noga i krok.

Gdzie:

  • Trasa: cała podróż od początkowego punktu pośredniego przez dowolne pośrednie punkty do jego docelowego punktu. Trasa składa się z co najmniej jednej nogi.

  • Krok: ścieżka od jednego punktu na trasie do kolejnego punktu na trasie. Każdy etap składa się z jednego lub większej liczby odrębnych kroków.

    Trasa zawiera osobną nogę dla każdej trasy prowadzącej do następnego punktu. Jeśli na przykład trasa obejmuje jeden punkt początkowy i jeden punkt docelowy, oznacza to, że trasa obejmuje jeden odcinek. Dla każdego dodatkowego punktu na trasie, który dodajesz do trasy po punkcie początkowym i docelowym, jest to tzw. pośredni punkt pośredni – interfejs API dodaje osobną nogę.

    Interfejs API nie dodaje nogi do pośredniego punktu przejścia. Na przykład trasa zawierająca punkt początkowy, przelotowy i pośredni punkt pośredni zawiera tylko 1 nogę od punktu początkowego do miejsca docelowego. Więcej informacji o przelotowych punktach pośrednich znajdziesz w artykule Definiowanie punktu przejścia.

  • Krok: pojedyncza instrukcja na końcu trasy. Krok to najbardziej atomowa jednostka trasy. Na przykład krok może pojawić się jako „Skręć w lewo przy Main Street”.

Informacje o odpowiedzi

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

  • routes, tablica elementów typu Trasa. Tablica routes zawiera 1 element na każdą trasę zwracaną przez interfejs API. Tablica może zawierać maksymalnie 5 elementów: trasę domyślną, przyjazną dla środowiska i maksymalnie 3 alternatywne trasy.

  • geocodingResults, tablica elementów typu GeocodingResults. W przypadku każdej lokalizacji w żądaniu (źródło, miejsce docelowe lub pośredni punkt pośredni), która została określona jako ciąg adresu lub kod Plus, interfejs API wyszukuje identyfikator miejsca. Każdy element tej tablicy zawiera identyfikator miejsca odpowiadający lokalizacji. Lokalizacje wymienione w żądaniu określone jako identyfikator miejsca lub jako szerokość lub długość geograficzna są ignorowane.

  • fallbackInfo typu FallbackInfo. Jeśli interfejs API nie jest w stanie obliczyć trasy na podstawie wszystkich właściwości wejściowych, może skorzystać z innego sposobu obliczania. Jeśli używasz tego trybu, w tym polu znajdziesz szczegółowe informacje o odpowiedzi zastępczej. W innym przypadku 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)
  }
}

Tablica tras

Odpowiedź zawiera tablicę routes, w której każdy element tablicy jest typu Trasa. Każdy element tablicy reprezentuje całą trasę od punktu początkowego do miejsca docelowego. Interfejs API zawsze zwraca co najmniej jedną trasę, nazywaną domyślną.

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

Zidentyfikuj każdą trasę w tablicy, korzystając z właściwości tablicy routeLabels. Właściwość tablicy routeLabels zawiera:

Wartość Opis
DEFAULT_ROUTE Określa trasę domyślną.
FUEL_EFFICIENT Określa trasę przyjazną dla środowiska.
DEFAULT_ROUTE_ALTERNATE Wyznacz alternatywną trasę.

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

{
  "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 aktualną sytuację na drodze i inne czynniki trasa domyślna i ekologiczna mogą być takie same. W tym przypadku tablica routeLabels zawiera zarówno etykiety DEFAULT_ROUTE, jak i FUEL_EFFICIENT.

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

Informacje o tablicy nóg

Każdy element route w odpowiedzi zawiera tablicę legs, gdzie każdy element tablicy legs ma typ RouteLeg. Każdy etap tej tablicy określa ścieżkę od jednego punktu na trasie do kolejnego punktu na trasie. Trasa zawsze zawiera co najmniej 1 nogę.

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

{
  "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, gdzie każdy element tablicy steps jest typu RouteLegStep. Krok odpowiada pojedynczej instrukcji na nodze. Noga zawsze zawiera co najmniej 1 krok.

Każdy element w tablicy steps zawiera właściwość navigationInstruction typu NawigacjaInstrukcja, która zawiera instrukcje krokowe. 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 kroku obejmują informacje na temat tego kroku, takie jak distanceMeters, duration i polyline:

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

Określanie języka instrukcji

Interfejs API stara się wyświetlać instrukcje dotyczące trasy dostępne zarówno dla użytkownika, jak i użytkowników lokalnych. Aby osiągnąć ten cel, funkcja ta zwraca informacje o trasie w języku lokalnym, a w razie potrzeby transliterację do skryptu odczytanego przez użytkownika z uwzględnieniem preferowanego języka. Wszystkie komponenty adresu są zwracane w tym samym języku.

  • Jeśli parametr languageCode nie jest określony, interfejs API próbuje użyć preferowanego języka wskazanego w nagłówku Accept-Language.

  • Użyj parametru languageCode żądania, aby wyraźnie ustawić język trasy na liście obsługiwanych języków. Google często aktualizuje obsługiwane języki, więc ta lista może nie być pełna.

  • Jeśli nazwa jest niedostępna w preferowanym języku, interfejs API używa najbliższego dopasowania.

  • Preferowany język ma niewielki wpływ na zestaw wyników zwracanych przez interfejs API oraz kolejność ich zwracania. Geokoder interpretuje skróty w zależności od języka, np. skróty dla typu ulicy oraz synonimy prawidłowe w danym języku, ale nie w innym. Na przykład utca i tér to synonimy słowa „ulica” po węgiersku.

Informacje o tablicy geocodingResults

W przypadku każdego miejsca w żądaniu (punktu początkowego, miejsca docelowego lub pośredniego punktu końcowego), które zostało określone jako ciąg adresu lub jako kod Plus, interfejs API stara się znaleźć najbardziej pasującą lokalizację o odpowiednim identyfikatorze miejsca. Każdy element tablicy geocodingResults zawiera pole placeID zawierające lokalizację jako identyfikator miejsca oraz pole type określające typ lokalizacji, np. street_address, premise lub airport.

Tablica geocodingResults zawiera 3 pola:

  • origin: jeśli został podany jako ciąg adresu lub kod Plus Code, identyfikator miejsca pochodzenia. W przeciwnym razie to pole zostanie pominięte w odpowiedzi.

  • destination: jeśli został określony jako ciąg adresu lub kod Plus, identyfikator miejsca docelowego. W przeciwnym razie to pole zostanie pominięte w odpowiedzi.

  • intermediates: tablica zawierająca identyfikator miejsca dowolnego pośredniego punktu końcowego określonego jako ciąg adresu lub kod Plus Code. Jeśli pośredni punkt pośredni został określony jako identyfikator miejsca lub jako współrzędne lub szerokość geograficzna, jest on pomijany w odpowiedzi. Użyj właściwości intermediateWaypointRequestIndex w odpowiedzi, aby określić, który pośredni punkt pośredni w żądaniu odpowiada identyfikatorowi miejsca 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
        }
    ]
}