Żądanie linii łamanych

Metoda computeRoutes (REST) i metoda ComputeRoutes (gRPC) zwracają trasę reprezentowaną przez polilinię w ramach odpowiedzi. 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 dotyczące polilinii uwzględniającej natężenie ruchu są rozliczane według stawki preferencyjnej dla tras. Więcej informacji o płatnościach w przypadku interfejsu Routes API. Więcej informacji znajdziesz w artykule o konfigurowaniu jakości linii łamanej

Więcej informacji o poliliniach:

Przesyłanie podstawowej linii łamanej dla trasy, etapu lub kroku

Linia łamana jest reprezentowana przez obiekt Polyline (REST) lub Polyline (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 w odpowiedzi ścieżkę wieloliniową dla każdego kroku w ramach etapu, uwzględniając routes.legs.steps.polyline.

Aby na przykład zwrócić ścieżkę wieloliniową dla całej trasy, dla każdego etapu oraz dla każdego kroku 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 odpowiedź, która zawiera ścieżkę wielokąta dla trasy, dla każdego odcinka trasy i dla każdego kroku na odcinku:

{
  "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. W związku z tym linia łamana dla odcinka i dla trasy jest taka sama.

Jeśli do żądania dodasz punkt pośredni, zwrócona trasa będzie zawierać 2 odcinki:

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 zapytanie zwraca 2 odcinki, z których każdy ma niepowtarzalny wielokąt oraz wielokąt 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 złożonej

Jakość ścieżki wielokąta można opisać w tych terminach:

  • Precyzja punktów w postaci liczb zmiennoprzecinkowych

    Punkty są określane jako długość i szerokość geograficzna w formacie zmiennoprzecinkowym pojedynczej precyzji. Ta metoda sprawdza się w przypadku małych wartości (które można przedstawić dokładnie), ale dokładność maleje wraz ze wzrostem wartości z powodu błędów zaokrągleń w przypadku liczb zmiennoprzecinkowych.

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

  • Liczba punktów tworzących polilinię

    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.

Konfigurowanie typu kodowania linii złożonej

Użyj opcji żądania polylineEncoding, aby kontrolować typ linii łamanej. Właściwość polylineEncoding określa, czy linia złożona zostanie zakodowana jako ENCODED_POLYLINE (domyślnie), co oznacza, że zostanie użyty algorytm kodowania linii złożonej, czy GEO_JSON_LINESTRING, co oznacza, że zostanie użyty format GeoJSON LineString.

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ść polilinii jako HIGH_QUALITY lub OVERVIEW (domyślnie). W przypadku OVERVIEW linia złożona jest z małej liczby punktów i ma mniejsze opóźnienie żądania 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",
  ...
}

Prośba o linie łamane uwzględniające natężenie ruchu

Wszystkie przykłady pokazane powyżej zwracają podstawowe wielokąty, czyli wielokąty bez informacji o ruchu. Możesz też poprosić o to, aby linia wielokąta zawierała informacje o ruchu drogowym na trasie i na poszczególnych odcinkach.

Wielokąty uwzględniające natężenie ruchu zawierają informacje o warunkach na drodze na trasie. Warunki na drogach są wyrażane w kategoriach prędkości (NORMAL, SLOW, TRAFFIC_JAM) w przypadku danego przedziału odpowiedzi typu polilinia. Przedziały są definiowane przez indeksy punktów początkowych (włącznie) i końcowych (wyłącznie) ścieżki wielokąta.

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

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

Aby przesłać żądanie obliczenia ścieżki wielokąta uwzględniającej natężenie ruchu, 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. Zapytania dotyczące innych trybów podróży zwracają błąd.

  • W żądaniu podaj preferencję 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, podając w polu maski odpowiedzi wartość routes.travelAdvisory. 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 natężeniu ruchu, określ 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ą zakodowane w wielokącie i znajdują się w polu travelAdvisory obiektu typu RouteLegTravelAdvisory (każda odnoga) i obiektu RouteTravelAdvisory (trasy).

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ły zbiór obiektów obejmuje całą wielokątną ścieżkę bez nakładania się. Punkt początkowy określonego przedziału czasowego jest taki sam jak punkt końcowy poprzedniego przedział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 interwale odpowiada indeksowi 0 zgodnie z praktykami 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 łamanej

Użytkownicy pakietu Maps SDK mogą definiować niestandardową logikę mapowania między kategoriami prędkości a schematami renderowania linii złożonych. 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 artykułach Dostosowywanie wyglądu (Android) i Dostosowywanie linii złożonej (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