วิธีค้นหาจุดจอดขนส่งใกล้เคียงด้วย API ?

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

ในเอกสารสัญญา ROOTE roote-1.0.0 เส้นทาง GET /v1/transit/nearby จะค้นหาสถานที่ขนส่งที่อยู่ใกล้ ไม่ดึงข้อมูลการออกเดินทางหรือการแจ้งเตือนแบบเรียลไทม์ การค้นหาสถานที่กับการค้นหาการเดินทางครั้งถัดไปเป็นสองกระบวนการแยกกัน

กำหนดพารามิเตอร์

คำขอจะใช้ lat สำหรับละติจูด และ lng สำหรับลองจิจูด ชื่อแทน lon ก็อธิบายไว้ในเอกสารพารามิเตอร์ radius แสดงรัศมีเป็นเมตร; limit กำหนดจำนวนผลลัพธ์ที่ต้องการ ตัวกรอง modes สามารถกำหนดประเภทของการขนส่งได้

พิกัดนี้ใช้เป็นตัวอย่างสำหรับการค้นหาในเมืองบอร์โดซ์; ไม่ได้หมายถึงจุดจอดใดที่รับประกัน โปรดดูที่ เอกสารสัญญา OpenAPI ROOTE เพื่อดูขอบเขต ฟิลด์ และเงื่อนไขล่าสุด

ส่งคำขอครั้งแรกฝั่งเซิร์ฟเวอร์

นี่คือตัวอย่าง JavaScript สำหรับสภาพแวดล้อม Node.js ที่รองรับ fetch โทเค็น หากมีการใช้งาน จะเก็บในตัวแปรแวดล้อมฝั่งเซิร์ฟเวอร์ ตัวอย่างนี้ไม่จำเป็นต้องวางความลับในเบราว์เซอร์

async function rechercherArrets(token = process.env.ROOTE_API_TOKEN) {
  const url = new URL('https://api.roote.ai/v1/transit/nearby');
  url.search = new URLSearchParams({
    lat: '44.8378',
    lng: '-0.5792',
    radius: '600',
    limit: '10',
    modes: 'bus,tram'
  }).toString();

  const headers = { Accept: 'application/json' };
  if (token) headers.Authorization = `Bearer ${token}`;

  const response = await fetch(url, {
    headers,
    signal: AbortSignal.timeout(10000)
  });
  if (!response.ok) {
    throw new Error(`Erreur HTTP ${response.status}`);
  }

  const data = await response.json();
  if (data.contract_version !== 'roote-1.0.0') {
    throw new Error('Version du contrat non reconnue');
  }
  if (!['success', 'empty', 'partial'].includes(data.status)) {
    throw new Error('Recherche indisponible');
  }
  if (!Array.isArray(data.stations)) {
    throw new Error('Réponse sans collection stations valide');
  }

  return {
    status: data.status,
    stations: data.stations,
    lines: data.lines,
    operators: data.operators,
    coverage: data.coverage,
    warnings: data.warnings,
    attributions: data.attributions,
    meta: data.meta
  };
}

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

อ่านเอนทิตีและความสัมพันธ์ระหว่างพวกมัน

ชุดข้อมูล stations ประกอบด้วยสถานที่ที่ส่งคืน สำหรับแต่ละรายการ ให้ดูข้อมูล id, name, entity_kind, location และ distance_meters การอ้างอิง line_ids และ operator_ids ช่วยเชื่อมชุดข้อมูล lines และ operators เมื่อมีให้

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

ควรจัดการกับข้อมูลที่ไม่ทราบโดยชัดเจน ในเอกสาร accessibility.wheelchair อาจเป็น unknown ซึ่งไม่เท่ากับ yes หรือ no ความสามารถในการประกาศการออกเดินทางไม่เหมือนกับรายการการออกเดินทางจริง

แสดงรายการหรือแผนที่

ใช้รหัสประจำตัวเพื่อให้รายการในอินเทอร์เฟซเสถียร ใช้ชื่อสำหรับป้ายกำกับ และ location สำหรับตำแหน่ง เชื่อมโยงเส้นทางโดยการอ้างอิง แทนการจับคู่จากชื่อ

หากแสดงสีเส้นหรือป้ายกำกับจากข้อมูล ให้นำมาปฏิบัติเป็นข้อมูลภายนอกที่ต้องตรวจสอบ สำหรับชื่อ ควรใช้ข้อความแทน HTML ฝังกรณี Injection

เก็บรักษาแหล่งที่มาและแสดงผลลัพธ์ตามที่เอกสารระบุว่าจำเป็น

จัดการผลลัพธ์ว่าง การตอบกลับบางส่วน และข้อผิดพลาด

ผลลัพธ์ empty คือการค้นหาที่ไม่มีผลลัพธ์ในพื้นที่ที่รู้จัก ไม่ได้หมายความว่าไม่มีการขนส่งจริง การตอบ partial อาจมีสถานที่ที่มีประโยชน์แต่เตือนข้อจำกัด ต้องแสดงผลลัพธ์และคำเตือนอย่างเหมาะสม

อ่านข้อมูล coverage, warnings และข้อจำกัดใน meta รายการที่ถูกตัดทอนไม่ได้แสดงความครอบคลุมทั้งหมด หากเกิดข้อผิดพลาดเครือข่ายหรือ HTTP ควรแสดงสถานะไม่สามารถใช้ได้โดยไม่เปลี่ยนผลลัพธ์เป็น 'ไม่มีจุดจอด'

สำหรับรหัส 429 ให้ดูคำแนะนำสำหรับการลองใหม่และส่วนหัวที่บริการเป็นไปได้ หลีกเลี่ยงการเรียกซ้ำอย่างต่อเนื่อง

แยกความแตกต่างระหว่างสถานี โซน และชานชลา

ฟิลด์ entity_kind แยกระดับสถานที่ต่างๆ ผลลัพธ์สองรายการที่อยู่ใกล้กันอาจเป็นชานชลาด้านต่างกัน ชื่อที่คล้ายกันอาจมาจากแหล่งข้อมูลแตกต่างกัน

อย่ารวมสถานที่โดยอัตโนมัติแค่จากความใกล้ ใช้ความสัมพันธ์และตัวตนตามเอกสารของบริการ คู่มือของเรา GTFS, GTFS-RT และ GBFS อธิบายบริบทของข้อมูล

เตรียมการผสานใช้งานในสภาพแวดล้อมจริง

ส่งคำค้นหาหลังตำแหน่งหรือการตั้งค่าตัวกรองเปลี่ยนแปลงอย่างเป็นประโยชน์ รวมคำขอที่เหมือนกัน กำหนดเวลาเผื่อ และปรับแคชให้เหมาะสมกับประเภทข้อมูลและสภาวะของบริการ

รายการสถานที่และข้อมูลเวลาจริงมีข้อกำหนดความสดที่ต่างกัน ตรวจสอบเส้นทางด้วยคำตอบครบถ้วน, ว่าง, บางส่วน และข้อผิดพลาดก่อนแสดงผลให้ผู้ใช้

ขยายการค้นหาไปยังบริการในเมือง

ป้ายและบริการในเมืองใช้เส้นทางที่แยกกัน สำหรับการค้นหาห้องน้ำรอบจุดเดียวกัน เส้นทาง GET /v1/services/nearby จะรอรับ lat และ lon พร้อมพารามิเตอร์ types=toilets อย่าส่ง modes=toilets ไปยังเส้นทางนี้ เพราะศัพท์นี้ใช้กับ URL แผนที่ ไม่ใช่ตัวกรองบริการ

ตัวอย่าง JavaScript ต่อไปนี้สร้าง URL บริการสำหรับรัศมี 600 เมตร ซึ่งยังไม่ทำการเรียกขอข้อมูล; ใช้ควบคุม HTTP และสัญญาที่อธิบายไว้ก่อนหน้า การเก็บรวบรวมข้อมูลที่คาดหวังคือ services แทน stations เก็บ service_type, location, distance_meters และแอตทริบิวต์ที่มีจริงไว้

สัญญา REST เอกสารอธิบายบริการ ได้แก่ toilets, drinking_water, fountain, wifi, parking, charging, aed และ locker ประเภทที่ MCP แสดงอาจแตกต่างกัน สำหรับพารามิเตอร์ที่รับได้ ขอบเขต และข้อจำกัดของการเข้าถึง กรุณาตรวจสอบสกีมาของอินเทอร์เฟซที่ใช้งาน

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

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

const url = new URL('https://api.roote.ai/v1/services/nearby');
url.search = new URLSearchParams({
  lat: '44.8416106', lon: '-0.5810938',
  radius: '600', limit: '10', types: 'toilets'
}).toString();
console.log(url.toString());

วินิจฉัยการค้นหาที่ไม่มีผลลัพธ์หรือมีข้อผิดพลาด

ฝังแผนที่ที่กรองข้อมูลไว้ในเว็บไซต์โดยตรง

สร้างผู้ช่วยรอบการค้นหาเหล่านี้

คำถามที่พบบ่อย

Nearby ให้ข้อมูลการออกเดินทางครั้งถัดไปหรือไม่?

ไม่มีในเอกสารนี้ เส้นทางนี้ไปค้นหาสถานที่ขนส่ง ส่วนข้อมูลการเดินทางต้องใช้ความสามารถแยกต่างหาก

แสดงรายการว่างหลังข้อผิดพลาดได้ไหม?

ควรแสดงสถานะไม่พร้อมใช้งาน ข้อผิดพลาดไม่ได้แสดงว่าไม่มีจุดจอดจริง

เก็บโทเค็น API ไว้ในเบราว์เซอร์ได้ไหม?

ความลับควรเก็บไว้ฝั่งเซิร์ฟเวอร์ ใช้แบบจำลองการเข้าถึงตามที่ออกแบบสำหรับแอปพลิเคชันและบัญชีของคุณ