A AI Vision
進入儀表板

API 文檔

AI Vision 車輛辨識管理系統 RESTful API 完整使用說明

身份驗證

AI Vision API 使用 API Key 進行身份驗證。所有 API 請求都必須在 HTTP Header 中包含有效的 API Key。

重要提醒

請妥善保管您的 API Key，避免在公開場所或程式碼中暴露。建議使用環境變數或配置檔案管理。

請求標頭範例
X-API-Key: your-api-key-here

車輛管理 API

完整的車輛資料管理功能 — 新增、查詢、更新、刪除。

GET /api/vehicles/

取得車輛列表，支援多種篩選條件。

查詢參數

license_plate
string 車牌號碼（支援部分匹配，不區分大小寫）
is_identified
boolean 是否已辨識（true/false）
parking_lot_id
integer 停車場 ID
POST /api/vehicles/

建立新的車輛記錄。

請求參數

license_plate 必填
string 車牌號碼
image 必填
file 車輛圖片檔案
brand
string 車輛品牌
model
string 車輛車型
year
string 車輛年份
parking_lot_id
integer 停車場 ID
captured_at
datetime 拍攝時間（ISO 8601 格式）
GET /api/vehicles/{id}/

取得特定車輛的詳細資料。

PUT /api/vehicles/{id}/

完整更新車輛資料（需提供所有欄位）。

PATCH /api/vehicles/{id}/

部分更新車輛資料（只需提供要更新的欄位）。

DELETE /api/vehicles/{id}/

刪除車輛記錄。

PATCH /api/vehicles/{id}/update_identification/

更新車輛的辨識狀態和信心度分數。

請求參數

is_identified
boolean 是否已辨識
confidence_score
float 辨識信心度分數（0.0–1.0）

停車場管理 API

停車場資料的管理功能 — 新增、查詢、更新、刪除。

GET /api/parking-lots/

取得停車場列表，支援篩選功能。

查詢參數

site_id
string 場地 ID（支援部分匹配，不區分大小寫）
name
string 停車場名稱（支援部分匹配，不區分大小寫）
POST /api/parking-lots/

建立新的停車場。

請求參數

site_id 必填
string 場地 ID（唯一識別碼）
name 必填
string 停車場名稱
GET /api/parking-lots/by-site-id/{site_id}/

透過場地 ID 查詢特定停車場。

停車記錄 API

停車場實時數據收集和管理 — 專為爬蟲系統設計的批量上傳介面。

GET /api/parking-records/

取得停車記錄列表，支援時間範圍和停車場篩選。

查詢參數

parking_lot_id
integer 停車場 ID
site_id
string 停車場場地 ID
start_date
datetime 開始時間（ISO 8601 格式）
end_date
datetime 結束時間（ISO 8601 格式）
POST /api/parking-records/batch-collect/

批量收集停車場資料 — 為爬蟲系統設計，每 10 分鐘可調用一次。

請求參數

timestamp
string 資料收集時間戳記（ISO 8601 格式）
summary
object 總體統計資訊（選填）
parking_lots 必填
array 停車場資料列表
停車場資料格式
{
  "parking_id": "74fe48598c5b",
  "last_update": "2025-07-03 17:06:27",
  "regular_occupied": 66,
  "regular_total": 200,
  "monthly_occupied": 46,
  "monthly_total": 100,
  "regular_available": 134,
  "monthly_available": 54
}

停車場物件欄位

parking_id 必填
string 停車場唯一識別碼
last_update
string 資料來源最後更新時間（YYYY-MM-DD HH:MM:SS）
regular_occupied
integer 一般停車位已使用數
regular_total
integer 一般停車位總數
monthly_occupied
integer 月租停車位已使用數
monthly_total
integer 月租停車位總數
regular_available
integer 一般停車位剩餘數（可為負）
monthly_available
integer 月租停車位剩餘數（可為負）
成功回應格式
{
  "success": true,
  "message": "成功處理 51 筆停車記錄",
  "statistics": {
    "created_lots": 5,
    "updated_lots": 0,
    "created_records": 51,
    "skipped_records": 0,
    "errors": 0,
    "total_processed": 51
  }
}
POST /api/parking-records/

建立單筆停車記錄。

請求參數

parking_lot 必填
integer 停車場 ID
regular_occupied
integer 一般停車位已使用數
regular_total
integer 一般停車位總數
monthly_occupied
integer 月租停車位已使用數
monthly_total
integer 月租停車位總數
last_update
datetime 資料來源更新時間（ISO 8601）
GET /api/parking-records/{id}/

取得特定停車記錄的詳細資料。

使用範例

以下是常見的 API 使用範例，幫助您快速上手。

上傳車輛圖片

curl -X POST "https://your-domain.com/api/vehicles/" \
  -H "X-API-Key: your-api-key" \
  -F "license_plate=ABC-1234" \
  -F "brand=Toyota" \
  -F "model=Camry" \
  -F "year=2020" \
  -F "image=@/path/to/vehicle.jpg"

查詢特定車牌

curl -X GET "https://your-domain.com/api/vehicles/?license_plate=ABC" \
  -H "X-API-Key: your-api-key"

更新辨識狀態

curl -X PATCH "https://your-domain.com/api/vehicles/1/update_identification/" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "is_identified": true,
    "confidence_score": 0.95
  }'

建立停車場

curl -X POST "https://your-domain.com/api/parking-lots/" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "SITE-001",
    "name": "主停車場"
  }'

批量上傳停車場資料（爬蟲使用）

curl -X POST "https://your-domain.com/api/parking-records/batch-collect/" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2025-07-03T17:10:14.524615",
    "summary": {
      "total_parking_lots": 51,
      "total_regular_spaces": 23578,
      "total_regular_occupied": 4010
    },
    "parking_lots": [
      {
        "parking_id": "74fe48598c5b",
        "last_update": "2025-07-03 17:06:27",
        "regular_occupied": 66,
        "regular_total": 200,
        "monthly_occupied": 46,
        "monthly_total": 100,
        "regular_available": 134,
        "monthly_available": 54
      }
    ]
  }'

查詢停車記錄

特定停車場的記錄
curl -X GET "https://your-domain.com/api/parking-records/?site_id=74fe48598c5b&start_date=2025-07-03T00:00:00Z" \
  -H "X-API-Key: your-api-key"
時間範圍內的所有記錄
curl -X GET "https://your-domain.com/api/parking-records/?start_date=2025-07-03T00:00:00Z&end_date=2025-07-03T23:59:59Z" \
  -H "X-API-Key: your-api-key"