Để tìm các điểm dừng quanh một vị trí, hãy truyền vào vĩ độ, kinh độ và bán kính vào API định vị gần. Sau đó kiểm tra trạng thái phản hồi, các thực thể trả về và thông tin phạm vi trước khi hiển thị danh sách hoặc bản đồ.
Trong hợp đồng ROOTE roote-1.0.0, tuyến GET /v1/transit/nearby dùng để tìm các địa điểm giao thông gần đó. Tuyến này không lấy dữ liệu khởi hành hay cảnh báo thời gian thực. Việc tìm địa điểm và tìm chuyến tiếp theo là hai thao tác riêng biệt.
Đặt các tham số
Yêu cầu sử dụng lat cho vĩ độ và lng cho kinh độ. Bí danh lon cũng được mô tả trong hợp đồng. Tham số radius thể hiện bán kính tính bằng mét; limit giới hạn số kết quả yêu cầu. Bộ lọc modes có thể xác định các loại phương tiện giao thông.
| Tham số | Ví dụ | Ý nghĩa |
|---|---|---|
| lat | 44.8378 | Vĩ độ của điểm tìm kiếm |
| lng | -0.5792 | Kinh độ của điểm tìm kiếm |
| radius | 600 | Bán kính yêu cầu tính bằng mét |
| limit | 10 | Giới hạn số kết quả yêu cầu |
| modes | bus,tram | Các loại phương tiện tìm kiếm |
Các tọa độ này là ví dụ tìm kiếm ở Bordeaux; không đảm bảo đây là điểm dừng chính xác. Xem hợp đồng OpenAPI ROOTE để biết giới hạn, trường và điều kiện hiện tại.
Tìm điểm dừng quanh bạn.
Khám phá các điểm dừng được ghi nhận quanh thành phố hoặc vị trí của bạn. Xem chi tiết để kiểm tra loại phương tiện và thông tin có sẵn.
Gửi yêu cầu đầu tiên phía máy chủ
Dưới đây là ví dụ JavaScript cho môi trường Node.js có fetch. Token, nếu bạn dùng, được giữ trong biến môi trường phía máy chủ. Ví dụ này không cần đặt bí mật trong trình duyệt.
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
};
}
Hợp đồng cho phép truy cập ẩn danh hoặc có token tùy theo chính sách. Kiểm tra quyền và giới hạn truy cập. Phản hồi HTTP hợp lệ vẫn cần kiểm tra nội dung; trong sản xuất, cũng nên xác thực đối tượng theo schema.
Đọc các thực thể và mối quan hệ của chúng
Bộ sưu tập stations chứa các địa điểm trả về. Với mỗi phần tử, xem các trường id, name, entity_kind, location và distance_meters. Các tham chiếu line_ids và operator_ids giúp liên kết đến collections lines và operators nếu có.
Hiển thị khoảng cách địa lý như nó vốn có. Không chuyển đổi thành thời gian đi bộ nếu không có tính toán lộ trình. Hướng dẫn tìm điểm dừng gần giải thích vì sao các lối tiếp cận có thể khác với di chuyển thực tế.
Cũng xử lý thông tin không xác định rõ ràng. Trong hợp đồng, accessibility.wheelchair có thể là unknown: giá trị này không tương đương yes hay no. Sức chứa chuyến khởi hành thông báo không phải danh sách chuyến khởi hành.
Hiển thị danh sách hoặc bản đồ
Dùng id để ổn định phần tử giao diện, tên để label và location để định vị. Liên kết các tuyến qua tham chiếu thay vì ghép tên.
Nếu hiển thị màu hoặc label tuyến từ dữ liệu, coi là dữ liệu ngoài cần xác thực. Với tên, dùng văn bản thay vì HTML chèn trực tiếp.
Giữ các quyền tác giả nguồn và hiển thị những quyền theo yêu cầu hợp đồng.
Xử lý kết quả rỗng, phản hồi một phần và lỗi
Kết quả empty mô tả không có dữ liệu trả về trong phạm vi biết; không chứng minh không có phương tiện. Phản hồi partial có thể có dữ liệu hữu ích và cảnh báo giới hạn: hiển thị cả hai.
Đọc coverage, warnings và các giới hạn trong meta. Danh sách cắt không mô tả phạm vi đầy đủ. Khi lỗi mạng hay HTTP, hiển thị trạng thái không khả dụng, không thay bằng ‘không có điểm dừng’.
Với mã 429, xem hướng dẫn xử lý và header dịch vụ. Tránh lặp lại yêu cầu liên tục.
Phân biệt stations, zones và platforms
Trường entity_kind phân biệt các cấp độ địa điểm. Hai kết quả gần nhau có thể là nền tảng (platform) khác nhau; hai tên tương tự có thể thuộc nguồn khác nhau.
Không tự động gộp địa điểm chỉ dựa trên gần nhau. Dùng mối quan hệ và ID do dịch vụ cung cấp. Hướng dẫn GTFS, GTFS-RT và GBFS giải thích ngữ cảnh dữ liệu.
Chuẩn bị tích hợp vào sản xuất
Kích hoạt tìm kiếm khi vị trí hoặc bộ lọc thay đổi có ích. Gộp các yêu cầu giống nhau, đặt thời gian chờ và tùy chỉnh bộ nhớ đệm theo loại dữ liệu và điều kiện dịch vụ.
Danh sách địa điểm và dữ liệu thời gian thực có yêu cầu tươi mới khác nhau. Kiểm thử đầy đủ với phản hồi đầy đủ, rỗng, một phần và lỗi trước khi phục vụ người dùng.
Mở rộng tìm kiếm đến các dịch vụ trong đô thị
Các trạm dừng và dịch vụ đô thị sử dụng các tuyến đường riêng biệt. Để tìm nhà vệ sinh quanh cùng một điểm, tuyến GET /v1/services/nearby yêu cầu lat và lon, với types=toilets. Không gửi modes=toilets cho tuyến này: từ vựng này thuộc URL bản đồ, không thuộc bộ lọc Dịch vụ.
Ví dụ JavaScript sau xây dựng một URL Dịch vụ với bán kính 600 mét. Nó không kích hoạt truy vấn; hãy tái sử dụng các kiểm soát HTTP và hợp đồng đã mô tả ở trên. Bộ sưu tập mong đợi là services, thay vì stations. Giữ lại service_type, location, distance_meters và các thuộc tính thực sự có mặt.
Hợp đồng REST mô tả cụ thể toilets, drinking_water, fountain, wifi, parking, charging, aed và locker. Các loại được MCP phơi bày có thể khác nhau. Để biết các tham số được chấp nhận, giới hạn và hạn mức truy cập của bạn, hãy tham khảo sơ đồ giao diện đang sử dụng.
Các thuộc tính của một dịch vụ không đảm bảo nó mở cửa tại thời điểm tìm kiếm. Khả năng truy cập không xác định không đồng nghĩa với dịch vụ không khả dụng; danh sách rỗng do lỗi không chứng minh không có nhà vệ sinh. Giữ dữ liệu riêng biệt theo từng nhóm dịch vụ thay vì gom chúng thành một tên và một điểm duy nhất.
Cho bản đồ tổng hợp, kết hợp kết quả với nhóm và định danh của chúng. Hiển thị lỗi Dịch vụ mà không xóa các trạm trả về bởi Transit. Tìm kiếm vẫn tập trung quanh cùng một điểm, nhưng trạng thái và phạm vi có thể khác nhau.
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());Chẩn đoán tìm kiếm không có kết quả hoặc lỗi
Nhúng trực tiếp một bản đồ đã lọc vào trang web
Xây dựng một trợ lý quanh các tìm kiếm này
Câu hỏi thường gặp
Nearby có cung cấp chuyến khởi hành sắp tới không?
Không trong hợp đồng này. Tuyến chỉ tìm địa điểm giao thông; chuyến khởi hành cần API riêng.
Có thể hiển thị danh sách rỗng sau lỗi không?
Hiển thị trạng thái không khả dụng. Lỗi không chứng minh không có điểm dừng.
Có thể đặt token API trong trình duyệt không?
Bí mật phải ở phía máy chủ. Dùng mô hình truy cập thích hợp với ứng dụng và tài khoản của bạn.