Określ lokalizacje na trasie

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Jeśli Twój adres rozliczeniowy znajduje się w Europejskim Obszarze Gospodarczym, od 8 lipca 2025 r. do korzystania z usług będą miały zastosowanie Warunki korzystania z usługi Google Maps Platform w EOG. Funkcje różnią się w zależności od regionu. Więcej informacji

Aby obliczyć trasę, musisz podać co najmniej lokalizację początku i końca trasy. Te lokalizacje definiujesz jako punkty pośrednie na trasie.

Oprócz punktu początkowego i docelowego możesz określić różne typy punktów pośrednich i sposób ich obsługi na trasie. Więcej informacji i przykładów znajdziesz w tych tematach:

• Określanie kierunku jazdy pojazdu i strony drogi
• Określanie punktów pośrednich
• Ustawianie przystanku na trasie
• Ustawianie punktu, przez który ma przebiegać trasa
• Optymalizacja kolejności przystanków na trasie

Określanie lokalizacji na trasie

Lokalizację reprezentujesz, tworząc obiekt Waypoint (REST) lub Waypoint (gRPC). W definicji punktu pośredniego możesz określić lokalizację na jeden z tych sposobów:

• Identyfikator miejsca
• Współrzędne geograficzne
• Ciąg znaków adresu („Chicago, IL” lub „Darwin, NT, Australia”)
• Token punktu nawigacyjnego
• Plus Code

Lokalizacje wszystkich punktów pośrednich w żądaniu możesz określić w ten sam sposób lub możesz je mieszać. Możesz na przykład użyć współrzędnych geograficznych dla punktu początkowego i identyfikatora miejsca dla punktu docelowego.

Aby zwiększyć wydajność i dokładność, używaj identyfikatorów miejsc zamiast współrzędnych geograficznych lub ciągów znaków adresu. Identyfikatory miejsc są jednoznaczne i zapewniają korzyści związane z geokodowaniem na potrzeby wyznaczania tras, takie jak punkty dostępu i zmienne dotyczące ruchu. Pomagają one uniknąć tych sytuacji, które mogą wystąpić w przypadku innych sposobów określania lokalizacji:

• Użycie współrzędnych geograficznych może spowodować, że lokalizacja zostanie przypisana do najbliższej drogi, która może nie być punktem dostępu do obiektu ani nawet drogą, która szybko lub bezpiecznie prowadzi do celu.
• Ciągi adresów muszą najpierw zostać przekształcone przez interfejs Routes API na współrzędne szerokości i długości geograficznej, aby można było obliczyć trasę. Ta konwersja może wpłynąć na skuteczność.

Określanie lokalizacji za pomocą identyfikatora miejsca

Aby określić lokalizację punktu pośredniego, możesz użyć identyfikatora miejsca. Współrzędne długości i szerokości geograficznej są dopasowywane do dróg, więc w niektórych przypadkach identyfikator miejsca może dawać lepsze wyniki.

Pobieraj identyfikatory miejsc z Geocoding API i Places API (w tym z funkcji autouzupełniania miejsc). Więcej informacji o identyfikatorach miejsc znajdziesz w tym artykule.

W tym przykładzie użyto właściwości placeId, aby przekazać identyfikator miejsca zarówno w przypadku origin, jak i destination:

{
  "origin":{
    "placeId": "ChIJayOTViHY5okRRoq2kGnGg8o"
  },
  "destination":{
    "placeId": "ChIJTYKK2G3X5okRgP7BZvPQ2FU"
  },
  ...
}

Określanie lokalizacji za pomocą współrzędnych geograficznych

Aby zdefiniować lokalizację w punkcie pośrednim, określ Location (REST) lub Location(gRPC), używając współrzędnych geograficznych.

Możesz na przykład określić punkt pośredni dla trasy origin i destination, używając współrzędnych latitude i longitude:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
...
}

Uwaga: punkty określone przez współrzędne geograficzne są przyciągane do dróg i mogą nie zapewniać dokładności wymaganej przez Twoją aplikację. Używaj współrzędnych geograficznych, gdy masz pewność, że wartości rzeczywiście określają punkty, których aplikacja potrzebuje do wyznaczania trasy, bez względu na możliwe punkty dostępu lub dodatkowe szczegóły geokodowania.

Określanie lokalizacji jako ciągu znaków adresu

Ciągi adresowe to dosłowne adresy reprezentowane przez ciąg znaków (np. „1600 Amphitheatre Parkway, Mountain View, CA”). Geokodowanie to proces konwertowania ciągu znaków adresu na współrzędne szerokości i długości geograficznej (np. szerokość geograficzna 37.423021 i długość geograficzna -122.083739).

Gdy przekazujesz ciąg znaków adresu jako lokalizację punktu pośredniego, interfejs Routes API wewnętrznie geokoduje ten ciąg znaków, aby przekonwertować go na współrzędne geograficzne.

Uwaga: współrzędne szerokości i długości geograficznej mogą się różnić od tych zwracanych przez Geocoding API. Na przykład interfejs Routes API może zwracać współrzędne wejścia do budynku, a nie jego środka.

Aby na przykład obliczyć trasę, możesz określić punkt pośredni origin i destination za pomocą ciągów znaków adresu:

{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "450 Serra Mall, Stanford, CA 94305, USA"
  },
  ...
}

W tym przykładzie interfejs Routes API geokoduje oba adresy, aby przekształcić je we współrzędne długości i szerokości geograficznej.

Jeśli wartość adresu jest niejednoznaczna, interfejs Routes API może wywołać wyszukiwanie, aby odróżnić go od podobnych adresów. Na przykład „1st Street” może być pełną lub częściową wartością dla „1st street NE” lub „1st St SE”. Ten wynik może się różnić od wyniku zwracanego przez Geocoding API. Aby uniknąć możliwych błędnych interpretacji, możesz używać identyfikatorów miejsc.

Ustawianie regionu adresu

Jeśli jako lokalizację punktu pośredniego podasz niepełny ciąg znaków adresu, interfejs API może użyć nieprawidłowych współrzędnych geograficznych. Na przykład wysyłasz żądanie, w którym jako miejsce docelowe podajesz „Toledo”, a jako miejsce docelowe „Madryt” w przypadku trasy samochodowej:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE"
}

W tym przykładzie „Toledo” jest interpretowane jako miasto w stanie Ohio w Stanach Zjednoczonych, a nie w Hiszpanii. Dlatego żądanie zwraca pustą tablicę, co oznacza, że nie ma żadnych tras:

{
  []
}

Możesz skonfigurować interfejs API tak, aby zwracał wyniki z określonego regionu, uwzględniając parametr regionCode. Ten parametr określa kod regionu jako dwuznakową wartość ccTLD („domena najwyższego poziomu”). Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma istotnymi wyjątkami. Na przykład krajowa domena najwyższego poziomu Zjednoczonego Królestwa to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”).

Żądanie wskazówek dojazdu z „Toledo” do „Madrytu” zawierające parametr regionCode zwraca odpowiednie wyniki, ponieważ „Toledo” jest interpretowane jako miasto w Hiszpanii:

{
  "origin":{
    "address": "Toledo"
  },
  "destination":{
    "address": "Madrid"
  },
  "travelMode": "DRIVE",
  "regionCode": "es"
}

Odpowiedź zawiera teraz trasę obliczoną z Toledo w Hiszpanii do Madrytu w Hiszpanii:

{
  "routes": [
    {
      "distanceMeters": 75330,
      "duration": "4137s",
      ...
    }
  ]
}

Określanie lokalizacji jako tokenu punktu nawigacyjnego

Ta usługa lub funkcja jest w wersji testowej (przed GA). Usługi i funkcje przed GA mogą mieć ograniczoną obsługę, a zmiany w takich usługach i funkcjach mogą być niezgodne z ich innymi wersjami. Oferty przed GA są objęte szczegółowymi warunkami korzystania z usługi Google Maps Platform. Więcej informacji znajdziesz w opisach etapu uruchamiania.

Token punktu nawigacyjnego to ciąg znaków, który koduje lokalizację i dodatkowy kontekst trasy. Tokeny punktów nawigacyjnych mogą zapewniać precyzyjne wyznaczanie trasy do konkretnych punktów dostępu w pobliżu wejść, doków załadunkowych lub wyznaczonych miejsc odbioru. Jest to przydatne w przypadku usług takich jak dostawa jedzenia czy przejazdy, w których punkt odbioru lub docelowy może być niejednoznaczny.

Token punktu nawigacyjnego możesz uzyskać, wywołując metodę Destinations w interfejsie Geocoding API.

Aby określić token punktu nawigacyjnego:

1. Uzyskaj navigationPointToken z metody `SearchDestinations` w Geocoding API. Więcej informacji znajdziesz w dokumentacji interfejsu Geocoding API
2. Utwórz punkt pośredni, przekazując navigationPointToken.

W tym przykładzie użyto właściwości navigation_point_token, aby przekazać token punktu nawigacyjnego zarówno dla origin, jak i destination:

{
  "origin":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_ORIGIN"
  },
  "destination":{
    "navigation_point_token": "ENCODED_NAVIGATION_POINT_TOKEN_FOR_DESTINATION"
  },
  ...
}

Określanie lokalizacji za pomocą kodu Plus Code

Wiele osób nie ma dokładnego adresu, co może utrudniać im odbiór przesyłek. Osoby z adresem mogą też woleć odbierać przesyłki w bardziej konkretnych miejscach, np. przy tylnym wejściu lub na rampie załadunkowej.

Kody Plus Code działają jak adresy dla osób lub miejsc, które nie mają rzeczywistego adresu. Kody plus nie zawierają nazw ulic ani numerów budynków, ale opierają się na współrzędnych szerokości i długości geograficznej i są wyświetlane jako liczby i litery.

Google opracowało kody Plus Code, aby każdy mógł korzystać z zalet adresów. Kod plus to zakodowany odnośnik do lokalizacji, który jest wyznaczany na podstawie współrzędnych geograficznych (długości i szerokości) i reprezentuje obszar o wielkości 1/8000 stopnia na 1/8000 stopnia (około 14 m × 14 m na równiku) lub mniejszy. Kodów Plus Code możesz używać zamiast adresów w miejscach, w których nie istnieją lub w których budynki nie są ponumerowane albo ulice nie mają nazw.

Kody Plus Code muszą być sformatowane jako kod globalny lub kod złożony:

• Kod globalny składa się z 4-znakowego kodu obszaru i 6-znakowego lub dłuższego kodu lokalnego.

  Na przykład dla adresu „1600 Amphitheatre Parkway, Mountain View, CA” kod globalny to „849V”, a kod lokalny to „CWC8+R9”. Następnie użyj całego 10-znakowego kodu plus, aby określić wartość lokalizacji jako „849VCWC8+R9”.

• Kod złożony składa się z co najmniej 6-znakowego kodu lokalnego połączonego z określoną lokalizacją.

  Na przykład adres „450 Serra Mall, Stanford, CA 94305, USA” ma kod lokalny „CRHJ+C3”. W przypadku adresu złożonego połącz kod lokalny z miastem, stanem, kodem pocztowym i krajem w formacie „CRHJ+C3 Stanford, CA 94305, USA”.

  Możesz na przykład obliczyć trasę, podając punkt pośredni trasy origin i destination za pomocą kodów plus:

  {
    "origin":{
      "address": "849VCWC8+R9"
    },
    "destination":{
      "address": "CRHJ+C3 Stanford, CA 94305, USA"
    },
    "travelMode": "DRIVE"
  }

Kody Plus są obsługiwane w interfejsach Google Maps Platform API, w tym w autouzupełnianiu miejsc, szczegółach miejsca, Directions API (starsza wersja) i Geocoding API. Możesz na przykład użyć interfejsu Geocoding API do geokodowania odwrotnego lokalizacji określonej przez współrzędne geograficzne, aby określić kod Plus Code tej lokalizacji.