Skip to content

About

台灣停車場即時空位查詢 CLI:給座標回報附近停車場、剩幾格、導航連結。座標查詢不需金鑰。

Resources

Stars

8 stars

Watchers

0 watching

Forks

Repository files navigation

tw-parking

台灣停車場即時空位查詢的命令列工具。給一個座標或地址,回報附近的停車場、還剩幾格、 以及一條可以直接點開導航的連結。

大部分功能不需要任何金鑰。 主要資料源是公開端點,near <lat> <lon> 開箱即用。

$ python3 parking.py near 25.047697 121.515114 --radius 500

1. 臺北車站西側地上停車場
   143m|🟢 23/96|即時|計時:小型車100元/時、機車30元/時
   https://www.google.com/maps/dir/?api=1&destination=25.047629,121.516532

2. 臺北車站西區地下停車場
   153m|🟢 17/179|即時|計時:100元/時
   https://www.google.com/maps/dir/?api=1&destination=25.047854,121.516622

燈號

燈號 意思
🟢 還有 3 格以上
🟡 只剩 1 到 2 格
🔴 0 格
❓ 查不到,或資料太舊(超過 24 小時)不敢給數字

過期的即時值一律降成 ❓ 不給燈號。拿一天前的數字當現況等於騙人,寧可說不知道。

資料來源

分四層,由上而下遞補:

  1. parkboss.tw — 全國涵蓋最廣的一層,六都的即時空位大多來自這裡
  2. 縣市政府自有端點 — 屏東、嘉義、彰化、雲林、新竹、台東、南投等 10 個
  3. 本地靜態庫(static-store.json)— 屏東縣路外、嘉義縣、新竹縣三份開放資料 只給地址不給經緯度,事先轉好座標存成一份檔案,查詢時零額外請求
  4. TDX 運輸資料流通服務 — 只在前三層查不到的縣份出手(苗栗、金門),需要免費金鑰

用法

python3 parking.py near <lat> <lon> [--radius 800] [--limit 3] [--json]
python3 parking.py near-address "<地址或地標>"      # 需要 Google 金鑰,見下

常用選項:

  • --radius 搜尋半徑,公尺,預設 800
  • --limit 列幾個,預設 3,0 代表全部
  • --include-moto 連機車專用場一起列(預設濾掉)
  • --json 輸出結構化資料,不受 --limit 影響(截斷會讓下游誤以為附近只有三個場)

排序規則:先分 500 公尺帶,帶內優先給查得到空位的,再按距離。「已知 0 格」排在 「不知道」後面——已知客滿比未知更糟,去了一定白跑。

給 AI 助理用(MCP)

mcp_server.py 把這支工具包成一台 MCP server,走 stdio。它在你自己的機器上跑, 不是連到誰的伺服器:MCP client 把它當子程序啟動,查詢直接從你的機器打向資料源。

Claude Desktop 之類的設定檔寫法:

{
  "mcpServers": {
    "tw-parking": {
      "command": "python3",
      "args": ["/絕對路徑/tw-parking/mcp_server.py"]
    }
  }
}

提供一個工具 find_parking,參數 lat、lon、radius、limit、include_moto, 回傳結構化的停車場清單(含 navigation_url 導航連結)。沒有第三方套件依賴。

呈現規範(給接上這支工具的 AI)

工具回的是 JSON,不是給人看的。工具描述裡已經寫了下面這套規範,模型每次呼叫都讀得到; 你自己接的時候如果模型沒照做,把這段貼給它就會對齊:

  • 每個停車場一列,欄位順序:燈號、停車場名稱、距離、剩餘 / 總車位、費率
  • 燈號照 availability_status 對:available=🟢、low=🟡、full=🔴、unknown=❓
  • 停車場名稱直接做成超連結,指向 navigation_url(點名字就開導航,不另外貼一串網址)
  • unknown 的場不寫車位數字,原因是資料超過 24 小時,寧可說不知道
  • 最後一句話推薦一個場(最近且有位優先),並帶上 car_time 的資料時間

ChatGPT 與 Claude 網頁版照這套會排成一張表,名稱可點、燈號在最前面。

會執行 shell 的代理(Claude Code、Codex CLI、Cursor 之類)其實不必走 MCP, 直接呼叫 python3 parking.py near <lat> <lon> --json 更省事。

選用設定(都不設也能跑)

環境變數 作用
GOOGLE_MAPS_API_KEY 開啟 near-address 地址查詢(Geocoding API)
TDX_CLIENT_ID / TDX_CLIENT_SECRET 開啟第四層 TDX;也可寫進 ~/.config/parking/tdx.env
TDX_CRED_FILE 改憑證檔位置
PARKING_CACHE_DIR 改快取目錄,預設 ~/.cache/parking
PARKING_SHORTLINK_CMD 把導航長網址換成短網址的指令,收一個參數印一行
PARKING_SHORTLINK_PREFIX 短網址應有的開頭,用來擋掉指令印出奇怪東西

短網址走本地台帳去重:多數縮網址服務每收到一次請求就發一個新短碼,同一個場查十次 就在後端留十筆垃圾。場的座標不會變,所以一個場一輩子只該有一個短碼。

已知限制

  • 機車專用場的過濾是盡力而為:資料源沒有車種欄位,只能看名字帶「機車」而且不帶 「汽」——「汽機車停車場」那種兩種都收不能濾掉。漏網之魚有可能發生。
  • 總格數 0 視同沒公布,只印剩餘不印分母;有些來源用 0 表示未知容量。
  • 跨來源合併靠名字比對,完全同名才無條件放行;包含關係要求較短的那個 6 字以上 且核心名不是「第一停車場」「站前停車場」這類通用名,否則跨鄉鎮同名場會互相吃到 對方的空位數。
  • 少數政府端點的 TLS 憑證鏈不完整,程式對名單內的特定主機放寬驗證。名單寫死在 sources.py,新增來源不會安靜地跟著吃 CERT_NONE。

資料來源與顯名聲明

程式碼是 MIT,資料不是。本專案內含與取用的政府開放資料依 政府資料開放授權條款第 1 版 使用,該條款允許再散布與商業利用, 但要求標示原資料提供機關。隨附的 static-store.json(351 筆,只有場名、地址、座標、格數、費率) 就是這樣的衍生資料:

  • 屏東縣政府「路外公共停車場」「恆春鎮停車場」開放資料(120 筆)
  • 嘉義縣政府停車場開放資料(93 筆)
  • 新竹縣政府停車場開放資料(138 筆)
  • 執行期間另即時取用:彰化縣、雲林縣、花蓮縣、臺東縣、南投縣、澎湖縣政府的停車場端點
  • 交通部「TDX 運輸資料流通服務平臺」(第四層,需自行申請免費金鑰)

以上依政府資料開放授權條款第 1 版利用。parkboss.tw 是民間服務,非政府開放資料, 本專案只是以一般使用者身分讀取其公開端點。

對資料來源的禮貌:所有對外請求都有快取,請不要把節流拿掉——這些是縣市政府的機器, 不是設計來承受大量請求的。

層 快取 說明
parkboss 與 10 個縣府端點 60 秒(PARKING_HTTP_TTL) 每次查詢會併行打全部縣府端點,快取讓連續查詢不會重複打
本地靜態庫 不必 讀本地檔案,零請求
TDX 場資 7 天、即時空位 60 秒 免費方案實測連打第 6 發就 429,這層節流最嚴

PARKING_HTTP_TTL=0 可以關掉 HTTP 快取,但沒有理由這樣做——即時空位本來就以分鐘計。

授權

程式碼採 MIT;資料照上一節的授權條款。

遠端版(Cloudflare Worker)

worker/ 是同一支查詢邏輯的 TypeScript 移植,跑在 Cloudflare Workers 上,給跑不了本機程式的 AI 網頁版用 (ChatGPT/Claude/Gemini 的網頁介面接不到 stdio MCP,只能接 HTTP)。行為跟 Python 版對齊: 同一個 find_parking 工具、同樣的四層資料源、同樣的新鮮度與燈號判斷。

公開端點(開放模式,不用金鑰):

https://parking.life-os.work

MCP client 設定裡加一台 HTTP 型 server 指到這個網址即可(根路徑與 /mcp 都收 MCP 請求); GET /health 回 {"ok":true} 可拿來探活。

接進 ChatGPT 網頁版

需要 Plus/Pro/Business 帳號,而且只能在網頁版設定(設好之後手機 App 也能用)。

圖解版(每一步附手機畫面示意):https://dev.life-os.work/pub/tw-parking-setup/

  1. 左下角頭像 → 設定 → 外掛程式,捲到最下面點 開發人員模式
  2. 打開 開發者模式 開關(會標「風險提升」,這是所有自訂 MCP 都會有的提示)
  3. 回到 外掛程式 頁,右上角 + 新增外掛程式,填:
    • 名稱:tw-parking MCP
    • 說明:台灣停車場查詢
    • 連線:選 伺服器 URL,填 https://parking.life-os.work
    • 驗證:無驗證
    • 勾「我了解並想繼續」→ 建立
  4. 跳出「將 tw-parking MCP 新增至 ChatGPT」按 連線,之後在「已安裝」列裡會看到它
  5. 新對話直接問「宜蘭國小附近哪裡好停車」,它會自己呼叫 find_parking

接進 Claude 網頁版

免費方案也能加自訂連接器,同樣設好之後手機 App 也看得到。

圖解版(每一步附手機畫面示意):https://dev.life-os.work/pub/tw-parking-setup/#claude

  1. 左下角頭像 → Settings → 左欄 Connectors,右上角 Add
  2. 跳出 Add custom connector,填:
    • Name:TW Parking
    • URL:https://parking.life-os.work/mcp (⚠️ 填的是 MCP 端點,不是這個 GitHub 頁面的網址;貼 repo 網址會拿到 429/422 之類的錯誤)
    • 按 Continue
  3. Authentication 會自動偵測到 No sign-in(標 Detected),保持這個選項;Request headers 不用加,直接往下按新增
  4. 回到 connectors 清單點 TW Parking,畫面寫 You're not connected yet,按 Connect
  5. 連上後會列出 Tool permissions,只有一個 Find parking;右邊下拉選 Always allow,之後每次查停車就不會再跳確認
  6. 新對話直接問「宜蘭國小附近哪裡好停車」,它會自己呼叫 find_parking

兩邊都不用金鑰,因為公開端點跑在開放模式;每個 IP 每分鐘 20 次的限流是在 Cloudflare 那層擋的。 自己架一份、想鎖權杖或改限流,看下一節。

自己架一份

cd worker
npm install
npx wrangler kv namespace create TOKENS   # 把回傳的 id 填進 wrangler.toml
npx wrangler deploy
  • 上游回應用 Cache API 快取 60 秒(TW_PARKING_HTTP_TTL 可調,0=不快取)
  • 要鎖權杖:wrangler secret put TW_PARKING_TOKEN,並把 [vars] 的 TW_PARKING_OPEN 拿掉;之後 POST 要帶 Authorization: Bearer <token>
  • 要接 TDX(苗栗、金門那層):wrangler secret put TDX_CLIENT_ID 與 TDX_CLIENT_SECRET,token 會存在 KV 裡重用到過期;沒設就跳過那層,其他三層照常
  • 免費方案每次呼叫 CPU 10 毫秒、子請求 50 次;台東那層只對半徑內最近的 12 座場站抓細節(超過時日誌印一行筆數),其餘照 Python 版
  • 本機開發:npx wrangler dev --local,再跑 tests/parity.sh <基準網址> http://127.0.0.1:8787 對照兩邊回同樣的場站

About

台灣停車場即時空位查詢 CLI:給座標回報附近停車場、剩幾格、導航連結。座標查詢不需金鑰。

Resources

Stars

8 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages