Krótkie wprowadzenie do interfejsu Distance Matrix API

Distance Matrix API (starsza wersja) to usługa internetowa, która zwraca odległość i czas podróży dla macierzy miejsc rozpoczęcia i zakończenia podróży na podstawie zalecanej trasy między każdą parą. Możesz ustawić środek transportu (samochód, pieszo, rower, transport publiczny), środki transportu publicznego, jednostki i czas wyjazdu w przypadku czasu trwania podróży zależnego od natężenia ruchu. Zwraca dane w formacie JSON lub XML.

Distance Matrix API: najważniejsze informacje

  • Usługa: Distance Matrix API
  • Inne nazwy: Distance Matrix API (starsza wersja), Distance Matrix (starsza wersja)
  • Kategoria: Trasy
  • Platforma: usługa internetowa (REST)
  • Działa na: serwerze (kod backendu)
  • Etap uruchomienia: GA
  • Cykl życia: starsza wersja
  • Zastąpiony przez: Routes API
  • Omówienie: omówienie interfejsu Distance Matrix API

Distance Matrix API: kiedy z niego korzystać

Kiedy używać interfejsu Distance Matrix API:

  • Utrzymujesz istniejący projekt, który ma już włączony interfejs Distance Matrix API (starsza wersja) i wywołuje metodę /maps/api/distancematrix.
  • Potrzebujesz odległości i czasu podróży między kilkoma punktami początkowymi i kilkoma miejscami docelowymi z serwera.
  • Potrzebujesz czasu przejazdu samochodem w ruchu ulicznym, używając departure_time i opcjonalnie traffic_model.

Nie używaj interfejsu Distance Matrix API, gdy:

  • Rozpoczynasz nowy projekt Google Cloud. Od października 2026 r. interfejsu Distance Matrix API (starsza wersja) nie będzie można włączać w nowych projektach. Zamiast tego użyj interfejsu Routes API.
  • Potrzebujesz nowych funkcji lub macierzy tras zawierającej maksymalnie 625 elementów z odpowiedziami przesyłanymi strumieniowo (computeRouteMatrix). Zamiast tego użyj interfejsu Routes API.
  • Potrzebujesz pełnej trasy z etapami i liniami łamanymi między punktami, a nie tylko wartości odległości i czasu trwania. Zamiast tego użyj interfejsu Routes API.

Distance Matrix API: konfiguracja

Distance Matrix API: typowe błędy

  • Problem: każde żądanie po stronie serwera jest ograniczone do 100 elementów (miejsca początkowe × miejsca docelowe) oraz do 25 miejsc początkowych lub 25 miejsc docelowych. Większe żądania zwracają błąd MAX_ELEMENTS_EXCEEDED lub MAX_DIMENSIONS_EXCEEDED. Rozwiązanie: podziel macierz na żądania zawierające nie więcej niż 100 elementów i 25 miejsc początkowych lub docelowych. Zobacz /maps/documentation/distance-matrix/usage-and-billing#usage-limits.
  • Problem: jeśli nie określisz parametru departure_time, trasa i czas trwania będą obliczane na podstawie średniego natężenia ruchu niezależnego od czasu, a parametr duration_in_traffic nie zostanie zwrócony. Wyniki mogą się zmieniać z czasem. Rozwiązanie: ustaw departure_time na now lub na przyszłą godzinę za pomocą mode=driving, aby uzyskać czas trwania uwzględniający natężenie ruchu. Pamiętaj, że żądania dotyczące ruchu są rozliczane według wyższej stawki. Zobacz /maps/documentation/distance-matrix/distance-matrix.
  • Problem: parametr units zmienia tylko tekst w polach odległości. Wartość odległości jest zawsze podawana w metrach. Rozwiązanie: odczytuj distance.value jako metry lub używaj distance.text do wyświetlania. Zobacz /maps/documentation/distance-matrix/distance-matrix.
  • Problem: wywołanie interfejsu Distance Matrix API (starsza wersja) z projektu, w którym nie jest on włączony, zwraca błąd REQUEST_DENIED w status i error_message z linkiem do LegacyApiNotActivatedMapError. Asystenci AI często domyślnie generują kod starszych interfejsów API. Rozwiązanie: migruj do interfejsu Routes API computeRouteMatrix (z nagłówkiem X-Goog-FieldMask). Aktywuj starszą wersję interfejsu API za pomocą formularza tylko jako rozwiązanie krótkoterminowe. Zobacz /maps/legacy#LegacyApiNotActivatedMapError.