ขอไทม์ไลน์ของเส้นทาง

เมธอด computeRoutes (REST) และเมธอด ComputeRoutes (gRPC) จะส่งกลับเส้นทางที่แสดงด้วยเส้นประกอบซึ่งเป็นส่วนหนึ่งของ คำตอบ API เหล่านี้แสดงเส้นประกอบ 2 ประเภทดังนี้

  • เส้นประกอบพื้นฐาน (ค่าเริ่มต้น) แสดงเส้นทางแต่ไม่มีการจราจร ที่ฝังอยู่ในเส้นประกอบ คำขอที่แสดงเส้นประกอบพื้นฐาน จะเรียกเก็บเงินในอัตราพื้นฐานของ Routes ดูข้อมูลเพิ่มเติมเกี่ยวกับ การเรียกเก็บเงินสำหรับ Routes API

  • เส้นประกอบที่รับรู้การจราจรได้ มีข้อมูลเกี่ยวกับสภาพการจราจร ตลอดเส้นทาง สภาพการจราจรจะแสดงในรูปแบบความเร็ว หมวดหมู่ (NORMAL, SLOW, TRAFFIC_JAM) ที่เกี่ยวข้องในช่วงเวลาที่ระบุ เส้นประกอบ ระบบจะเรียกเก็บเงินคำขอสำหรับเส้นประกอบที่รับรู้การเข้าชมได้ที่ เส้นทางอัตราที่ต้องการ ดูข้อมูลเพิ่มเติมเกี่ยวกับการเรียกเก็บเงินสำหรับ Routes API โปรดดูรายละเอียดที่หัวข้อ กำหนดค่าคุณภาพเส้นประกอบ

ดูข้อมูลเพิ่มเติมเกี่ยวกับเส้นประกอบได้ที่

ขอเส้นประกอบพื้นฐานสําหรับเส้นทาง ขา หรือก้าว

เส้นประกอบจะแสดงเป็นเส้น Polyline (REST) หรือ ออบเจ็กต์ Polyline (gRPC) คุณจะแสดงผลเส้นประกอบในคำตอบได้ที่ระดับเส้นทาง ขา และระดับก้าว

ระบุเส้นประกอบที่จะส่งคืนโดยใช้ มาสก์ของช่องตอบกลับ:

  • ที่ระดับเส้นทาง ให้แสดงเส้นประกอบในคำตอบโดยใส่ routes.polyline ในมาสก์ของช่องคำตอบ

  • ที่ระดับขา ให้แสดงเส้นประกอบในการตอบสนองสำหรับขาแต่ละข้างของ เส้นทางโดยรวม routes.legs.polyline

  • ที่ระดับขั้นตอน ให้แสดงเส้นประกอบในคำตอบสำหรับแต่ละขั้นตอนของ โดยใช้ routes.legs.steps.polyline ด้วย

เช่น ในการแสดงเส้นประกอบของทั้งเส้นทาง สำหรับขาแต่ละข้าง และสำหรับ ในแต่ละก้าวของแต่ละช่วง

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'

คำขอนี้ส่งคืนการตอบกลับต่อไปนี้ซึ่งมีเส้นประกอบสำหรับ เส้นทาง แต่ละก้าวของเส้นทาง และสำหรับแต่ละขั้นตอนของขา

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

เนื่องจากคำขอนี้มีเพียงต้นทางและปลายทาง คำขอที่แสดงผล เส้นทางมีเพียงขาเดียว ดังนั้น เส้นประกอบของขาและ เหมือนกัน

หากคุณเพิ่มจุดอ้างอิงตรงกลางลงในคำขอ ค่าที่ส่งคืน เส้นทางมี 2 ส่วน ได้แก่

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'

คำขอนี้แสดงขา 2 ข้าง แต่ละขามีเส้นประกอบที่ไม่ซ้ำกัน และเส้นประกอบสำหรับ เส้นทางทั้งหมด:

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

คุณภาพเส้นประกอบ

คุณภาพของเส้นประกอบสามารถอธิบายได้ด้วยคำต่อไปนี้

  • ความแม่นยำของจุดลอยตัวของจุด

    จุดต่างๆ จะระบุเป็นค่าละติจูดและลองจิจูด ซึ่งเป็นค่าที่แสดง ในรูปแบบของจุดลอยตัวความแม่นยําเดียว วิธีนี้ใช้ได้ผลดีกับค่าที่น้อย (ซึ่งแสดงได้อย่างแม่นยำ) แต่ความแม่นยำจะลดลงตามค่า เพิ่มขึ้นเนื่องจากข้อผิดพลาดในการปัดเศษทศนิยม

    ใน computeRoutes เมธอด (REST) และ ComputeRoutes ซึ่งควบคุมโดย polylineEncoding

  • จำนวนจุดที่รวมกันเป็นเส้นประกอบ

    ยิ่งมีจุดมาก เส้นพลาสติกจะยิ่งเนียนมากขึ้น (โดยเฉพาะอย่างยิ่ง เส้นโค้ง)

    ใน computeRoutes เมธอด (REST) และ ComputeRoutes ซึ่งควบคุมโดย polylineQuality

กำหนดค่าประเภทการเข้ารหัสโพลีไลน์

ใช้ตัวเลือกคำขอ polylineEncoding เพื่อควบคุมประเภทเส้นประกอบ พร็อพเพอร์ตี้ polylineEncoding ควบคุมว่าเส้นประกอบจะเข้ารหัสเป็น ENCODED_POLYLINE (ค่าเริ่มต้น) ซึ่งหมายความว่า รูปแบบอัลกอริทึมโพลีไลน์ที่เข้ารหัส จะใช้ หรือ GEO_JSON_LINESTRING ซึ่งหมายความว่า รูปแบบ GeoJSON LineString จะถูกนำมาใช้

ตัวอย่างเช่น ในส่วนเนื้อหาของคำขอ

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'

กำหนดค่าคุณภาพโพลีไลน์

polylineQuality ระบุคุณภาพของเส้นประกอบเป็น HIGH_QUALITY หรือ OVERVIEW (ค่าเริ่มต้น) ใน OVERVIEW เส้นประกอบจะเขียนขึ้นโดยใช้ จำนวนจุดและมีเวลาในการตอบสนองของคำขอต่ำกว่า HIGH_QUALITY

ตัวอย่างเช่น ในส่วนเนื้อหาของคำขอ

{
  "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",
  ...
}

ขอเส้นประกอบที่รับรู้การจราจรได้

ตัวอย่างที่แสดงด้านบนเส้นประกอบพื้นฐานทั้งหมด ซึ่งหมายถึงเส้นประกอบที่ไม่มี ข้อมูลการจราจร นอกจากนี้ คุณยังขอให้รูปหลายเหลี่ยมมี ข้อมูลการจราจรของเส้นทางนั้นๆ และในแต่ละขาของเส้นทาง

เส้นประกอบการรับรู้การจราจรมีข้อมูลเกี่ยวกับสภาพการจราจรพร้อมกับ เส้นทาง สภาพการจราจรแสดงในหมวดหมู่ความเร็ว (NORMAL, SLOW, TRAFFIC_JAM) ในช่วงเวลาที่ระบุของคำตอบ เส้นประกอบ ช่วงเวลาจะกำหนดโดยดัชนีของช่วงเริ่มต้น (รวม) และสิ้นสุดจุดโพลีไลน์ (ไม่รวม)

ตัวอย่างเช่น คำตอบต่อไปนี้แสดงการเข้าชม NORMAL ระหว่างเส้นประกอบ ประเด็นที่ 2 และ 4:

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

หากต้องการส่งคำขอคำนวณเส้นประกอบที่รับรู้การจราจรของข้อมูล ให้ตั้งค่าดังนี้ ที่พักในคำขอ:

  • ตั้งค่าช่องอาร์เรย์ extraComputations เป็น TRAFFIC_ON_POLYLINE เพื่อเปิดใช้ การคำนวณการเข้าชม

  • ตั้งค่า travelMode เป็น DRIVE หรือ TWO_WHEELER คำขออื่นๆ โหมดการเดินทางจะแสดงข้อผิดพลาด

  • ระบุเส้นทาง TRAFFIC_AWARE หรือ TRAFFIC_AWARE_OPTIMAL ค่ากำหนดสูงสุดในคำขอ สําหรับข้อมูลเพิ่มเติม โปรดดูการกําหนดค่าคุณภาพเทียบกับ เวลาในการตอบสนอง

  • ตั้งค่ามาสก์ฟิลด์การตอบกลับที่ระบุให้แสดงผลพร็อพเพอร์ตี้การตอบกลับ

    • ที่ระดับเส้นทาง ให้แสดงข้อมูลการเดินทางทั้งหมดในคำตอบภายใน รวมทั้ง routes.travelAdvisory ในมาสก์ฟิลด์ตอบกลับ เพื่อกลับ เฉพาะข้อมูลการจราจร ระบุ routes.travelAdvisory.speedReadingIntervals

    • ที่ระดับการเดินทาง ให้แสดงผลข้อมูลการเดินทางทั้งหมดในคำตอบสำหรับ แต่ละขาของเส้นทางโดยรวม routes.legs.travelAdvisory เพื่อกลับ เฉพาะข้อมูลการจราจร ระบุ 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'

ตัวอย่างการตอบสนองสำหรับเส้นประกอบที่รับรู้การเข้าชม

ในการตอบกลับ ข้อมูลการรับส่งข้อมูลจะได้รับการเข้ารหัสในเส้นประกอบและอยู่ใน ช่อง travelAdvisory ประเภท RouteLegTravelAdvisory (ในแต่ละขา) และ ออบเจ็กต์ RouteTravelAdvisory (เส้นทาง)

เช่น

{
  "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 และ RouteLegTravelAdvisory มีช่องอาร์เรย์ ที่เรียกว่า speedReadingIntervals ที่มีข้อมูลความเร็วการจราจร ชิ้น ในอาร์เรย์จะแสดงด้วย SpeedReadingInterval (REST) หรือ SpeedReadingInterval (gRPC)

ออบเจ็กต์ SpeedReadingInterval มีการอ่านความเร็วสำหรับช่วงของเส้นทาง เช่น NORMAL, SLOW หรือ TRAFFIC_JAM อาร์เรย์ของออบเจ็กต์ทั้งหมดครอบคลุม เส้นประกอบทั้งหมดของเส้นทางโดยไม่ทับซ้อนกัน จุดเริ่มต้นของฟิลด์ที่ระบุ ช่วงเวลาเท่ากับจุดสิ้นสุดของช่วงเวลาก่อนหน้า

ทุกช่วงมีคำอธิบายตาม startPolylinePointIndex endPolylinePointIndex และหมวดหมู่ความเร็วที่เกี่ยวข้อง โปรดสังเกตว่าการขาดดัชนีเริ่มต้นภายในช่วงสอดคล้องกับดัชนี 0 ตาม โปรโตคอล 3 ที่สามารถนำมาใช้ได้

ค่า startPolylinePointIndex และ endPolylinePointIndex ไม่เท่ากัน แบบเรียงต่อกันเสมอ เช่น

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

ในกรณีนี้ สภาพการจราจรเป็นไปในดัชนี 2 ถึงดัชนี 4

แสดงผลเส้นประกอบที่รับรู้การจราจรของข้อมูลด้วย Maps SDK

เราแนะนำให้แสดงเส้นประกอบการรับรู้การจราจรบนแผนที่โดยใช้ ฟีเจอร์ของ Google Maps SDK รวมถึงการลงสีที่กำหนดเอง เส้นโครงร่าง และ ลวดลายตามเส้นโพลีไลน์ที่ยืดออก สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับการใช้เส้นประกอบ ดู ฟีเจอร์ Polyline สำหรับ Android และฟีเจอร์ Polyline สำหรับ iOS

ตัวอย่างการแสดงผล Polyline

ผู้ใช้ Maps SDK มีโอกาสกำหนดการแมปที่กำหนดเอง ระหว่างหมวดหมู่ความเร็วและสคีมาการแสดงผลโพลีไลน์ ในฐานะ ตัวอย่างเช่น ผู้เข้าชมอาจตัดสินใจแสดงคำว่า "ปกติ" เป็นเส้นหนาสีน้ำเงินบน แผนที่ขณะ "ช้า" ความเร็วอาจแสดงเป็นเส้นหนาสีส้ม เป็นต้น

ข้อมูลโค้ดต่อไปนี้เพิ่มเส้นประกอบสีน้ำเงินหนาพร้อมส่วนที่มีกรอบเรขาคณิตจาก จากเมลเบิร์นไปเพิร์ท สำหรับข้อมูลเพิ่มเติม โปรดดู การปรับแต่งลักษณะที่ปรากฏ (สำหรับ Android) และ ปรับแต่งเส้นประกอบ (สำหรับ 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