Żądanie linii łamanych

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

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

  • Podstawowa linia łamana (domyślna), która reprezentuje trasę, ale bez informacji o ruchu osadzonych w linii łamanej. Żądania, które zwracają podstawową linię łamaną, są rozliczane według stawki Routes Basic. Więcej informacji o płatnościach za interfejs Routes API

  • Linia łamana uwzględniająca ruch, która zawiera informacje o warunkach na drodze na trasie. Warunki na drogach są wyrażane w kategoriach prędkości (NORMAL, SLOW, TRAFFIC_JAM) obowiązujących w danym przedziale linii łamanej. Żądania polilinii uwzględniających ruch są rozliczane według stawki Routes Preferred. Więcej informacji o płatnościach za interfejs Routes API. Szczegółowe informacje znajdziesz w artykule Konfigurowanie jakości polilinii.

Więcej informacji o liniach łamanych znajdziesz w tych artykułach:

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

Linia łamana jest reprezentowana przez obiekt Polyline (REST) lub Polyline (gRPC). W odpowiedzi możesz zwrócić linię łamaną na poziomie trasy, odcinka i kroku.

Aby określić, która linia łamana ma zostać zwrócona, użyj maski pola odpowiedzi:

  • Na poziomie trasy zwróć linię łamaną w odpowiedzi, uwzględniając routes.polyline w masce pola odpowiedzi.

  • Na poziomie odcinka zwracaj w odpowiedzi linię łamaną dla każdego odcinka trasy, uwzględniając parametr routes.legs.polyline.

  • Na poziomie kroku zwróć w odpowiedzi linię łamaną dla każdego kroku trasy, dodając parametr routes.legs.steps.polyline.

Aby na przykład zwrócić linię łamaną dla całej trasy, dla każdego etapu i 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 poniższą odpowiedź, która zawiera linię łamaną trasy, dla każdego odcinka trasy i dla każdego kroku odcinka:

{
  "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_@@_@?"
      }
    }
  ]
}

Ponieważ to żądanie zawiera tylko punkt początkowy i docelowy, zwrócona trasa zawiera tylko 1 odcinek. Dlatego linia łamana odcinka i trasy są takie same.

Jeśli do żądania dodasz punkt pośredni, zwrócona trasa będzie zawierać 2 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 odcinki, z których każdy ma unikalną 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ć w ten sposób:

  • Reprezentacja zmiennoprzecinkowa punktów

    Punkty są określane jako wartości szerokości i długości geograficznej, które są reprezentowane w formacie zmiennoprzecinkowym pojedynczej precyzji. Sprawdza się to w przypadku małych wartości (które można dokładnie przedstawić), ale precyzja maleje wraz ze wzrostem wartości ze względu na błędy zaokrąglania reprezentacji zmiennoprzecinkowej.

    W metodach computeRoutes (REST) i ComputeRoutes jest to kontrolowane przez parametr polylineEncoding.

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

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

    W metodach computeRoutes (REST) i ComputeRoutes jest to kontrolowane przez parametr polylineQuality.

Konfigurowanie typu kodowania linii łamanej

Użyj opcji żądania polylineEncoding, aby kontrolować typ linii łamanej. Właściwość polylineEncoding określa, czy linia łamana będzie kodowana jako ENCODED_POLYLINE (domyślnie), co oznacza, że zostanie użyty format algorytmu zakodowanej linii łamanej, czy jako 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'

Konfigurowanie jakości linii łamanej

polylineQuality określa jakość linii łamanej jako HIGH_QUALITY lub OVERVIEW (domyślnie). W przypadku OVERVIEW linia łamana jest tworzona przy użyciu niewielkiej liczby punktów i ma mniejszy 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",
  ...
}

Wysyłanie prośby o linię łamaną uwzględniającą ruch

Wszystkie powyższe przykłady zwracają podstawowe linie łamane, czyli linie łamane bez informacji o ruchu. Możesz też poprosić, aby linia łamana zawierała informacje o ruchu na trasie i na każdym jej odcinku.

Linie łamane uwzględniające ruch drogowy zawierają informacje o warunkach na drodze na trasie. Warunki na drogach są wyrażane w kategoriach prędkości (NORMAL, SLOW, TRAFFIC_JAM) dla danego przedziału linii łamanej odpowiedzi. Przedziały są zdefiniowane przez indeksy punktów linii łamanej, które wyznaczają ich początek (włącznie) i koniec (wyłącznie).

Na przykład poniższa odpowiedź pokazuje ruch NORMAL między punktami 2 i 4 linii łamanej:

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

Aby przesłać żądanie obliczenia linii łamanej uwzględniającej ruch, ustaw w nim te właściwości:

  • Ustaw pole tablicy extraComputations na TRAFFIC_ON_POLYLINE, aby włączyć obliczanie ruchu.

  • Ustaw wartość travelMode na DRIVE lub TWO_WHEELER. Żądania dotyczące innych środków transportu zwracają błąd.

  • W żądaniu określ preferencję routingu TRAFFIC_AWARE lub TRAFFIC_AWARE_OPTIMAL. Więcej informacji znajdziesz w artykule o konfigurowaniu jakości w porównaniu z opóźnieniem.

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

    • Na poziomie trasy zwróć w odpowiedzi wszystkie informacje o podróży, uwzględniając w masce pola odpowiedzi znak routes.travelAdvisory. Aby zwrócić tylko informacje o ruchu, określ routes.travelAdvisory.speedReadingIntervals.

    • Na poziomie odcinka zwracaj w odpowiedzi wszystkie informacje o podróży dla każdego odcinka trasy, uwzględniając element routes.legs.travelAdvisory. Aby zwrócić tylko informacje o 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ź dotycząca linii łamanej uwzględniającej ruch

W odpowiedzi dane o ruchu są zakodowane w linii łamanej i znajdują się w polu travelAdvisory typu RouteLegTravelAdvisory (każdy etap) i 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"
          }
        ] 
      }
    }
  ]
}

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

Obiekt SpeedReadingInterval zawiera odczyt prędkości dla przedziału trasy, np. NORMAL, SLOW lub TRAFFIC_JAM. Cała tablica obiektów pokrywa całą polilinię trasy bez nakładania się. Punkt początkowy określonego przedziału jest taki sam jak punkt końcowy poprzedniego przedziału.

Każdy przedział jest opisany przez startPolylinePointIndex, endPolylinePointIndex i odpowiednią kategorię prędkości. Zwróć uwagę, że brak indeksu początkowego w przedziale odpowiada indeksowi 0 zgodnie z zasadami proto3.

Wartości startPolylinePointIndex i endPolylinePointIndex nie zawsze są kolejne. Na przykład:

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

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

Renderowanie linii łamanych uwzględniających natężenie ruchu za pomocą pakietu Maps SDK

Zalecamy wyświetlanie na mapie linii łamanych uwzględniających ruch drogowy za pomocą różnych funkcji oferowanych przez pakiety SDK Map Google, w tym niestandardowych kolorów, obrysów i wzorów wzdłuż odcinków linii łamanej. Więcej informacji o korzystaniu z linii łamanych znajdziesz w sekcjach Funkcje linii łamanych na Androidzie i Funkcje linii łamanych na iOS.

Przykładowe renderowanie linii łamanej

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

Poniższe fragmenty kodu dodają grubą niebieską polilinię z odcinkami 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

Używanie zakodowanych linii łamanych w funkcji Szukaj na trasie

Użyj wyszukiwania tekstowego (nowość) w Places API (nowość), aby wyszukiwać wzdłuż obliczonej trasy. Do żądania Wyszukaj tekst (New) przekazujesz zakodowaną linię łamaną wstępnie obliczonej trasy z interfejsu Routes API Compute Routes. Odpowiedź zawiera miejsca, które pasują do kryteriów wyszukiwania i znajdują się w pobliżu określonej trasy. Więcej informacji znajdziesz w sekcji Wyszukiwanie wzdłuż trasy.

Aby na przykład wyświetlić kawiarnie na trasie między miejscem początkowym a docelowym:

Node.js

const API_KEY = 'YOUR_API_KEY';
const routes_service = 'https://routes.googleapis.com/directions/v2:computeRoutes';
const textSearch_service = 'https://places.googleapis.com/v1/places:searchText';



function init(){
    const routes_request = {
        "origin":{
            "address": "1600 Amphitheatre Parkway, Mountain View, CA"
        },
        "destination":{
            "address": "24 Willie Mays Plaza, San Francisco, CA 94107"
        },
        "travelMode": "DRIVE"
    };
    const textSearch_request = {
        "textQuery": "cafe",
        "searchAlongRouteParameters": {
            "polyline": {
                "encodedPolyline": ""
            }
        }
    };
    fetchResources(routes_service,routes_request).then(routes => {
        textSearch_request.searchAlongRouteParameters.polyline.encodedPolyline = routes.routes[0].polyline.encodedPolyline;
        fetchResources(textSearch_service,textSearch_request).then(places => {
            console.log(places);
        });
    });
}
async function fetchResources(resource,reqBody){
    const response = await fetch(resource, {
        method: 'POST',
        body: JSON.stringify(reqBody),
        headers: {
            'Content-Type': 'application/json',
            'X-Goog-Api-Key': API_KEY,
            'X-Goog-FieldMask': '*'
        }
    });
    const responseJSON = await response.json();
    return responseJSON;
}
init();