API 文檔

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

身份驗證

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

重要提醒

請妥善保管您的 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：

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：

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

更新辨識狀態

使用 curl：

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：

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：

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"