Żądanie linii łamanych

Zarówno metoda computeRoutes (REST), jak i metoda ComputeRoutes (gRPC) zwracają w odpowiedzi trasę reprezentowaną przez linię łamaną. Te interfejsy API zwracają 2 typy linii łamanych:

  • Podstawowa linia łamana (domyślnie) reprezentuje trasę, ale bez informacji o natężeniu ruchu umieszczonych w linii łamanej. Żądania zwracające podstawową linię łamaną są rozliczane według stawki podstawowej Trasy. Więcej informacji o płatnościach za interfejs Routes API.

  • Linia łamana z informacją o natężeniu ruchu zawiera informacje o ruchu drogowym na trasie. Warunki natężenia ruchu są wyrażone w postaci kategorii prędkości (NORMAL, SLOW, TRAFFIC_JAM) obowiązujących w danym odcinku linii łamanej. Żądania za żądania linii łamanych uwzględniające ruch są rozliczane według preferowanej stawki dla tras. Dowiedz się więcej o płatnościach za interfejs Routes API. Więcej informacji znajdziesz w artykule o konfigurowaniu jakości linii łamanej

Więcej informacji o liniach łamanych:

Żądanie podstawowej linii łamanej dla trasy, nogi lub kroku

Linia łamana jest reprezentowana przez obiekt linia łamana (REST) lub linia łamana (gRPC). Możesz zwrócić linię łamaną w odpowiedzi na poziomie trasy, etapu i kroku.

Określ, która linia łamana ma zostać zwrócona, używając maski pola odpowiedzi:

  • Na poziomie trasy, aby zwrócić linię łamaną w odpowiedzi, umieść znak routes.polyline w masce pola odpowiedzi.

  • Na poziomie nogi zwróć linię łamaną w odpowiedzi na każdy etap trasy, dodając routes.legs.polyline.

  • Na poziomie kroku zwracaj linię łamaną w odpowiedzi dla każdego kroku etapu, dodając routes.legs.steps.polyline.

Aby na przykład zwrócić linię łamaną na całej trasie, dla każdego odcinka i dla każdego etapu:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.legs.steps.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

To żądanie zwraca następującą odpowiedź zawierającą linię łamaną na trasie, każdy etap trasy i każdy etap trasy:

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
              "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
          }
        },
          "steps": [
              {
                  "polyline": {
                      "encodedPolyline": "kclcF...@sC@YIOKI"
                  }
              },
              {
                  "polyline": {
                      "encodedPolyline": "wblcF~...SZSF_@?"
                  }
              },
              ...
      ],
      "distanceMeters": 56901,
      "duration": "2420s",
      "polyline": {
        "encodedPolyline": "ipkcFfich...@Bs@?A?O?SD{A@o@B}@I?qA?_AA_@@_@?"
      }
    }
  ]
}

To żądanie zawiera tylko punkt początkowy i miejsce docelowe, więc zwrócona trasa zawiera tylko jeden etap. Dlatego linia łamana odcinka i trasy jest taka sama.

Jeśli dodasz do żądania pośredni punkt pośredni, zwrócona trasa będzie miała dwa etapy:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "intermediates": [
    { "address": "450 Serra Mall, Stanford, CA 94305, USA"},
  ],
  "travelMode": "DRIVE",
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

To żądanie zwraca 2 nogi, każdą z niepowtarzalną linią łamaną, oraz linię łamaną dla całej trasy:

{
  "routes": [
    {
      "legs": [
        {
          "polyline": {
            "encodedPolyline": "kclcFfqchV?A...?I@G?GAECCCEKICBAFG"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "kclcFfqch...YIOKI"
                }
            },
        ...
        },
        {
          "polyline": {
            "encodedPolyline": "ojmcFtethV?K...QOYQOGA?_@MUG[Ga@G"
          }
          "steps": [
            {
                "polyline": {
                    "encodedPolyline": "uypeFbo`jVgJq...PoBiC"
                }
            },
        ...
        }
      ],
      "distanceMeters": 68403,
      "duration": "3759s",
      "polyline": {
          "encodedPolyline": "kclcFfqchV?A?CBKF[Ha...?GAECCCEKICBAFGJEBE"
      }
    }
  ]
}

Jakość linii łamanej

Jakość linii łamanej można opisać za pomocą tych określeń:

  • Dokładność zmiennoprzecinkowa punktów

    Punkty są określane jako długość i szerokość geograficzna w formacie zmiennoprzecinkowym pojedynczej precyzji. Sprawdza się to w przypadku małych wartości (które można przedstawić dokładnie), ale precyzja zmniejsza się w miarę wzrostu wartości z powodu błędów zaokrąglania zmiennoprzecinkowego.

    W metodzie computeRoutes (REST) i ComputeRoutes kontroluje to polylineEncoding.

  • Liczba punktów tworzących linię łamaną

    Im więcej jest punktów, tym gładsza jest linia łamana (zwłaszcza w przypadku krzywych).

    W metodzie computeRoutes (REST) i ComputeRoutes kontroluje to polylineQuality.

Skonfiguruj typ kodowania linii łamanych

Użyj opcji żądania polylineEncoding, aby kontrolować typ linii łamanej. Właściwość polylineEncoding określa, czy linia łamana zostanie zakodowana jako ENCODED_POLYLINE (domyślnie), co oznacza, że zostanie użyty zakodowany format algorytmu łamanego, lub GEO_JSON_LINESTRING, co oznacza, że zostanie użyty format ciągu GeoJSON.

Na przykład w treści żądania:

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "polylineEncoding": "ENCODED_POLYLINE"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Skonfiguruj jakość linii łamanej

polylineQuality określa jakość linii łamanej jako HIGH_QUALITY lub OVERVIEW (domyślna). W funkcji OVERVIEW linia łamana składa się z niewielkiej liczby punktów i ma krótszy czas oczekiwania na żądanie niż HIGH_QUALITY.

Na przykład w treści żądania:

{
  "origin":{
    "location":{
      "latLng":{
        "latitude": 37.419734,
        "longitude": -122.0827784
      }
    }
  },
  "destination":{
    "location":{
      "latLng":{
        "latitude": 37.417670,
        "longitude": -122.079595
      }
    }
  },
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE",
  "polylineQuality": "HIGH_QUALITY",
  "polylineEncoding": "ENCODED_POLYLINE",
  "departureTime": "2023-10-15T15:01:23.045123456Z",
  ...
}

Żądanie linii łamanej wykrywającej ruch drogowy

Pokazane powyżej przykłady pokazują podstawowe linie łamane, co oznacza, że linie łamane są pozbawione informacji o natężeniu ruchu. Można również poprosić o dodanie do linii łamanej informacji o natężeniu ruchu na trasie i każdym jej etapie.

Linie łamane z informacją o ruchu drogowym na trasie zawierają informacje o warunkach na drodze. Warunki na drogach są wyrażone w postaci kategorii prędkości (NORMAL, SLOW, TRAFFIC_JAM) dla danego przedziału czasu linii łamanej odpowiedzi. Przedziały są określone przez indeksy ich początkowych (włącznie) i końcowych punktów linii łamanej.

Na przykład ta odpowiedź pokazuje ruch NORMAL między punktami 2–4 linii łamanej:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

Aby wysłać żądanie obliczenia linii łamanej wykrywającej ruch, ustaw w żądaniu te właściwości:

  • Aby włączyć obliczanie ruchu, ustaw pole tablicy extraComputations na TRAFFIC_ON_POLYLINE.

  • Ustaw travelMode na DRIVE lub TWO_WHEELER. Żądanie innego środka transportu zwraca błąd.

  • Określ w żądaniu ustawienie routingu TRAFFIC_AWARE lub TRAFFIC_AWARE_OPTIMAL. Więcej informacji znajdziesz w artykule Konfigurowanie jakości a czas oczekiwania.

  • Ustaw maskę pola odpowiedzi, która określa, że mają być zwracane właściwości odpowiedzi:

    • Na poziomie trasy, zwracaj wszystkie informacje o podróży w odpowiedzi, dodając routes.travelAdvisory do maski pola odpowiedzi. Aby zwrócić tylko informacje o ruchu, wpisz routes.travelAdvisory.speedReadingIntervals

    • Na poziomie nogi, w odpowiedzi na każdy etap trasy podaj wszystkie informacje dotyczące podróży, dodając routes.legs.travelAdvisory. Aby zwrócić tylko informacje o ruchu, wpisz routes.legs.travelAdvisory.speedReadingIntervals.

curl -X POST -d '{
  "origin":{
    "address": "1600 Amphitheatre Parkway, Mountain View, CA"
  },
  "destination":{
    "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
  },
  "travelMode": "DRIVE",
  "extraComputations": ["TRAFFIC_ON_POLYLINE"],
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline,routes.legs.polyline,routes.travelAdvisory,routes.legs.travelAdvisory' \
'https://routes.googleapis.com/directions/v2:computeRoutes'

Przykładowa odpowiedź dla linii łamanej wykrywającej ruch

W odpowiedzi dane o ruchu są kodowane w linii łamanej i znajdują się w polu travelAdvisory typu obiektu RouteLegTravelAdvisory (każdy etap) i obiektu RouteTravelAdvisory (trasa).

Na przykład:

{
  "routes": [
    {
      "legs": {
        "polyline": {
          "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
        },
        // Traffic data for the leg.
        "travelAdvisory": {
          "speedReadingIntervals": [
            {
              "endPolylinePointIndex": 1,
              "speed": "NORMAL"
            },
            {
              "startPolylinePointIndex": 1,
              "endPolylinePointIndex": 2,
              "speed": "SLOW"
            },
            {
              "startPolylinePointIndex": 2,
              "endPolylinePointIndex": 4,
              "speed": "NORMAL"
            }
          ] 
        }
      },
      "polyline": {
        "encodedPolyline": "}boeF~zbjVAg@EmB`GWHlD"
      },
      // Traffic data for the route.
      "travelAdvisory": {
        "speedReadingIntervals": [
          {
            "endPolylinePointIndex": 1,
            "speed": "NORMAL"
          },
          {
            "startPolylinePointIndex": 1,
            "endPolylinePointIndex": 2,
            "speed": "SLOW"
          },
          {
            "startPolylinePointIndex": 2,
            "endPolylinePointIndex": 4,
            "speed": "NORMAL"
          }
        ] 
      }
    }
  ]
}

RouteTravelAdvisory i RouteLegTravelAdvisory zawierają pole tablicy o nazwie speedReadingIntervals, które zawiera informacje o prędkości ruchu. Każdy obiekt w tablicy jest reprezentowany przez obiekt SpeedReadingInterval (REST) lub SpeedReadingInterval (gRPC).

Obiekt SpeedReadingInterval zawiera szybkość odczytu dla danego odcinka trasy, np. NORMAL, SLOW lub TRAFFIC_JAM. Cała tablica obiektów obejmuje całą linię łamaną trasy bez nakładania się. Punkt początkowy określonego interwału jest taki sam jak punkt końcowy poprzedniego interwału.

Każdy interwał jest opisany za pomocą właściwości startPolylinePointIndex, endPolylinePointIndex oraz odpowiedniej kategorii prędkości. Zwróć uwagę, że brak indeksu początkowego w danym przedziale odpowiada indeksowi 0 zgodnie z metodami Proto3.

Wartości startPolylinePointIndex i endPolylinePointIndex nie zawsze występują po sobie. Na przykład:

{
  "startPolylinePointIndex": 2,
  "endPolylinePointIndex": 4,
  "speed": "NORMAL"
}

W tym przypadku warunki ruchu były takie same od indeksu 2 do indeksu 4.

Renderowanie linii łamanych z uwzględnieniem natężenia ruchu za pomocą pakietu SDK Map Google

Zalecamy wyświetlanie na mapie linii łamanych z uwzględnieniem natężenia ruchu, korzystając z różnych funkcji oferowanych przez pakiety SDK Map Google, w tym niestandardowych kolorów, pociągnięć i wzorów na rozciąganych liniach łamanych. Więcej informacji o używaniu linii łamanych znajdziesz w artykułach Funkcje linii łamanej na Androidzie i Funkcje linii łamanej w iOS.

Przykład renderowania linii łamanych

Użytkownicy pakietu Maps SDK mogą zdefiniować niestandardową logikę mapowania między kategoriami szybkości a schematami renderowania łamanego. Na przykład prędkość „NORMALNA” może być wyświetlana na mapie grubą niebieską linią, a „WOLNA” – jako gruba pomarańczowa linia.

Poniższe fragmenty kodu dodają grubą niebieską linię łamaną z segmentami geodezyjnymi z Melbourne do Perth. Więcej informacji znajdziesz w sekcjach Dostosowywanie wyglądu (Android) i Dostosowywanie linii łamanej (iOS).

Android

Java

Polyline line = map.addPolyline(new PolylineOptions()
    .add(new LatLng(-37.81319, 144.96298), new LatLng(-31.95285, 115.85734))
    .width(25)
    .color(Color.BLUE)
    .geodesic(true));

Kotlin

val line: Polyline = map.addPolyline(
  PolylineOptions()
    .add(LatLng(-37.81319, 144.96298), LatLng(-31.95285, 115.85734))
    .width(25f)
    .color(Color.BLUE)
    .geodesic(true)
)

iOS

Objective-C

GMSMutablePath *path = [GMSMutablePath path];
[path addLatitude:-37.81319 longitude:144.96298];
[path addLatitude:-31.95285 longitude:115.85734];
GMSPolyline *polyline = [GMSPolyline polylineWithPath:path];
polyline.strokeWidth = 10.f;
polyline.strokeColor = .blue;
polyline.geodesic = YES;
polyline.map = mapView;

Swift

let path = GMSMutablePath()
path.addLatitude(-37.81319, longitude: 144.96298)
path.addLatitude(-31.95285, longitude: 115.85734)
let polyline = GMSPolyline(path: path)
polyline.strokeWidth = 10.0
polyline.geodesic = true
polyline.map = mapView