API Documentation

Lưu ý quan trọng: API này có giới hạn lượt truy xuất và chỉ được thiết kế cho các dự án cá nhân.
Nếu bạn có nhu cầu sử dụng cho dự án lớn, vui lòng liên hệ email: nghoanganhtuann@gmail.com

API này cung cấp khả năng truy cập dữ liệu công khai về kho lưu trữ hình ảnh xe buýt Việt Nam. Có thể sử dụng API để tích hợp dữ liệu vào các ứng dụng bên thứ ba, website cá nhân hoặc phục vụ mục đích nghiên cứu.

Base URL: https://vnbusarchive.qzz.io/api

Lấy danh sách ảnh

GET

Trả về danh sách các hình ảnh đã được duyệt, hỗ trợ lọc theo biển số, sắp xếp và phân trang.

GET /search

Tham số (Query Parameters)

Tham số Kiểu Mặc định Mô tả
plate string - Lọc theo biển kiểm soát xe (tìm kiếm gần đúng). Ví dụ: 51B
sort string created_at Tiêu chí sắp xếp. Giá trị: views (lượt xem) hoặc created_at (mới nhất).
limit integer 10 Số lượng kết quả trả về. Tối đa 10.

Ví dụ Request

curl -X GET "https://vnbusarchive.qzz.io/api/search?plate=51B&sort=views&limit=5" \
-H "Accept: application/json"

Ví dụ Response

{
  "success": true,
  "count": 1,
  "filter": {
    "plate": "51B",
    "sort": "views",
    "limit": 5
  },
  "data": [
    {
      "photo_id": 1024,
      "image_url": "https://supabase-storage-url...",
      "license_plate": "51B12345",
      "operator": "Hợp tác xã 19/5",
      "route": "150",
      "model": "Samco City I.40",
      "stats": {
        "views": 1542,
        "likes": 0
      },
      "uploader": "bus_spotter_sg",
      "location": "Bến xe Chợ Lớn",
      "posted_at": "2024-05-20T08:30:00.000Z"
    }
  ]
}

Cấu trúc đối tượng Photo

Dưới đây là chi tiết các trường dữ liệu trong mảng data trả về:

Trường Kiểu Mô tả
photo_id integer ID duy nhất của bức ảnh trong hệ thống.
image_url string Đường dẫn trực tiếp đến file ảnh.
license_plate string Biển kiểm soát của xe trong ảnh.
operator string Đơn vị vận hành (VD: VinBus, Transerco...). Trả về "Unknown" nếu chưa có dữ liệu.
route string|null Số hiệu tuyến hoặc lộ trình.
model string|null Dòng xe (Model chassis/body).
stats object Chứa thông tin thống kê: views (lượt xem), likes (lượt thích).
uploader string Tên người dùng đã đăng tải ảnh (hoặc "Anonymous").
location string Địa điểm chụp ảnh.
posted_at string Thời gian đăng tải (ISO 8601 format).

Mã lỗi (Errors)

API sử dụng các mã trạng thái HTTP tiêu chuẩn để chỉ ra sự thành công hoặc thất bại của request.

Code Status Mô tả
200 OK Request thành công.
500 Internal Server Error Lỗi máy chủ nội bộ. Response body sẽ chứa: { "success": false, "error": "Message" }