แนวทางปฏิบัติแนะนำสำหรับ Isochrone API

การปรับให้เรียบเนียนและความแม่นยำ

คุณสามารถปรับแต่งลักษณะและความแม่นยำของรูปหลายเหลี่ยมเอาต์พุตได้โดยใช้พารามิเตอร์ polygon_fidelity และ enable_smoothing แม้ว่าตัวเลือกเหล่านี้จะเป็นอิสระจากกัน แต่ก็ทำงานร่วมกันเพื่อกำหนดรูปร่างสุดท้าย

  • polygonFidelity (polygon_fidelity): ความละเอียด ควบคุมขนาดของเซลล์ตารางกริดเชิงพื้นที่ที่ใช้ในการคำนวณพื้นที่ที่เข้าถึงได้

    • LOW: ใช้เซลล์ตารางกริดที่ใหญ่ที่สุด (กว้างหลายร้อยเมตร) เหมาะที่สุดสำหรับการครอบคลุมพื้นที่ขนาดใหญ่โดยไม่มีช่องว่างและลดจำนวนจุดยอดให้เหลือน้อยที่สุด ส่งผลให้ได้รูปร่างทั่วไปที่อาจประเมินพื้นที่ที่เข้าถึงได้ตามทางเดินถนนแคบๆ สูงเกินไป
    • MEDIUM: ความแม่นยำและขนาดเพย์โหลดที่สมดุล
    • HIGH: ใช้เซลล์ตารางกริดที่เล็กที่สุด (ประมาณ 100-150 เมตร) ส่งผลให้พอดีกับเครือข่ายถนนมากขึ้น โดยมีจุดยอดมากขึ้น แต่อาจทำให้เกิดช่องว่างภายในที่เครือข่ายถนนเบาบาง
    • ค่าเริ่มต้น (POLYGON_FIDELITY_UNSPECIFIED): หากไม่ได้ระบุ บริการจะเลือกความละเอียดโดยอัตโนมัติตามรูปแบบการเดินทางและระยะเวลา โดยใช้เซลล์ที่ละเอียดขึ้นสำหรับระยะเวลาสั้นๆ และสำหรับ WALK และเซลล์ที่หยาบขึ้นสำหรับระยะเวลานาน หากต้องการเปรียบเทียบ Isochrone ในระยะเวลาหรือรูปแบบการเดินทางที่แตกต่างกัน ให้ตั้งค่า polygonFidelity อย่างชัดเจนเพื่อให้ใช้ความละเอียดเดียวกัน

    ขนาดเซลล์เป็นค่าโดยประมาณ Isochrone ขนาดใหญ่อาจได้รับการปรับให้เป็นภาพรวมมากขึ้นเพื่อรักษาขนาดการตอบกลับให้จัดการได้

  • enableSmoothing (enable_smoothing): สุนทรียศาสตร์ ควบคุมว่าจะปัดเศษขอบขั้นบันไดของเซลล์ตารางกริดที่กำหนดโดยความแม่นยำหรือไม่
    • false (ดิบ): แสดงขอบเขตที่จัดแนวตารางกริด ขอบจะปรากฏเป็นรอยหยักหรือขั้นบันได ซึ่งสะท้อนถึงเซลล์ตารางกริด เหมาะที่สุดสำหรับความแม่นยำในการวิเคราะห์ เช่น การทดสอบจุดในรูปหลายเหลี่ยมที่เข้มงวด
    • true (ปรับให้เรียบ): ปัดมุมให้โค้งมนโดยประมาณเพื่อคงพื้นที่ของแต่ละวงแหวนไว้ เหมาะสําหรับการแสดงภาพบนแผนที่ เนื่องจากขอบเขตไม่ได้เป็นไปตามเซลล์ตารางกริดอีกต่อไป จึงไม่ควรใช้ขอบเขตนี้สำหรับการทดสอบจุดในรูปหลายเหลี่ยมที่เข้มงวด

การโต้ตอบ: ความแม่นยำจะกำหนดรายละเอียดพื้นฐานที่อัลกอริทึมการปรับให้เรียบจะดำเนินการ

  • ความแม่นยำสูง + การปรับให้เรียบ: สร้างรูปร่างที่ดูเป็นธรรมชาติและมีรายละเอียดซึ่งสอดคล้องกับจุดสิ้นสุดของถนนอย่างใกล้ชิด
  • ความแม่นยำต่ำ + การปรับให้เรียบ: สร้างรูปร่าง "หยด" แบบกว้างๆ และทั่วไป

ขนาดเพย์โหลดและการแสดงผล

Isochrone ขนาดใหญ่ (โดยเฉพาะคำขอที่มีระยะเวลานานซึ่งมีความแม่นยำ HIGH) อาจมีพิกัดหลายหมื่นพิกัด และการตอบกลับ JSON ที่ไม่ได้บีบอัดอาจมีขนาดหลายร้อยกิโลไบต์ขึ้นไป

  • แบนด์วิดท์: โปรดทราบว่าขนาดการตอบกลับ JSON มีความสำคัญต่อคำขอระยะเวลาสูงสุดที่มีความแม่นยำสูง
  • การแสดงผล: การแสดงผลรูปหลายเหลี่ยมที่มีรายละเอียดสูงมากจะส่งผลต่อประสิทธิภาพของไคลเอ็นต์ หากต้องการลดจำนวนจุดยอดและขนาดเพย์โหลด ให้เลือก polygonFidelity: MEDIUM หรือ LOW หรือลดความซับซ้อนของเรขาคณิตในไคลเอ็นต์ก่อนแสดงผลโดยใช้อัลกอริทึมการลดความซับซ้อนของเส้น เช่น Douglas-Peucker

เวลาในการตอบสนองและระยะหมดเวลาของไคลเอ็นต์

เวลาในการตอบสนองจะเพิ่มขึ้นตามขนาดของเครือข่ายถนนที่เดินทางผ่าน โดยระยะเวลาสั้นๆ และโหมด WALK และ BICYCLE จะเร็วที่สุด ส่วนคำขอ DRIVE และ TWO_WHEELER ที่ใช้เวลานาน (โดยเฉพาะเมื่อใช้ TRAFFIC_AWARE) จะใช้เวลานานที่สุด

  • ระยะหมดเวลาของไคลเอ็นต์ที่แนะนำ: กำหนดค่ากำหนดเวลาของไคลเอ็นต์ HTTP หรือ gRPC เป็นอย่างน้อย 30 วินาที เพื่อไม่ให้คำขอที่ใช้เวลานานถูกยกเลิกก่อนเวลาอันควรเนื่องจากระยะหมดเวลาของไคลเอ็นต์สั้นเกินไป

การจัดการข้อผิดพลาด

ใช้ตรรกะการลองใหม่ด้วย Exponential Backoff และ Jitter สำหรับการตอบกลับการจำกัดอัตราคำขอ 429 RESOURCE_EXHAUSTED และข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ 5xx อย่าลองส่งคำขออีกครั้งเมื่อพบข้อผิดพลาดเกี่ยวกับไคลเอ็นต์ 400, 403 หรือ 404 โดยไม่เปลี่ยนแปลงคำขอ

  • INVALID_ARGUMENT (400): ตรวจสอบว่า travelDuration อยู่ระหว่าง 1s และ 3600s (DRIVE/TWO_WHEELER) หรือ 7200s (WALK/BICYCLE) location ไม่ได้ถูกละเว้นและไม่ใช่ (0, 0) (หรือ place เป็นรหัสสถานที่ที่ถูกต้อง) และ TRAFFIC_AWARE ใช้กับ DRIVE หรือ TWO_WHEELER เท่านั้น ระบบจะถือว่า latitude หรือ longitude ที่ละไว้เป็น 0.0 ดังนั้นการละไว้เพียงค่าเดียวมักจะไม่ทำให้เกิดข้อผิดพลาด 400 (เว้นแต่ว่าค่าอื่นจะเป็น 0.0 ด้วย) ตรวจสอบทั้ง 2 ค่าอีกครั้งหาก Isochrone ปรากฏในตำแหน่งที่ไม่ถูกต้อง
  • PERMISSION_DENIED (403): ตรวจสอบว่าได้ระบุคีย์ API หรือโทเค็น OAuth แล้ว และเปิดใช้ Isochrones API และการเรียกเก็บเงินในโปรเจ็กต์ Google Cloud แล้ว
  • NOT_FOUND (404): ไม่สามารถระบุตำแหน่งของ place หรือไม่สามารถสแนปจุดเริ่มต้นไปยังถนนใกล้เคียงที่ใช้ได้โดยโหมดการเดินทาง (ภายในระยะประมาณ 200 เมตรหรือน้อยกว่าสำหรับ WALK และ BICYCLE)
  • RESOURCE_EXHAUSTED (429): โปรเจ็กต์ของคุณมีคำขอเกินโควต้าต่อนาที (ค่าเริ่มต้นคือ 300 QPM) ลองอีกครั้งโดยใช้ Exponential Backoff