主題

開發者 API ​

郵遞區號隨手查提供免費的 RESTful API，讓開發者可以在自己的應用程式中整合台灣郵遞區號查詢功能。

基本資訊 ​

  • Base URL: https://ziptw.com/api
  • 格式: JSON
  • 認證: 不需要（有速率限制）
  • 速率限制: 100 次/天（以 IP 計算）

API 端點 ​

1. 地址查詢郵遞區號 ​

根據台灣地址查詢對應的 3碼、3+2、3+3 郵遞區號。

GET /api/zipcode?address={地址}

參數

參數類型必填說明
addressstring是台灣完整地址

範例請求

bash
curl "https://ziptw.com/api/zipcode?address=台北市中正區重慶南路一段122號"

範例回應

json
{
  "input": "台北市中正區重慶南路一段122號",
  "city": "臺北市",
  "district": "中正區",
  "zipcode_3": "100",
  "zipcode_32": "10045",
  "zipcode_33": "100201"
}

2. 反向查詢（郵遞區號 → 地址） ​

根據郵遞區號查詢對應的所有地址和路段。

GET /api/reverse?zipcode={郵遞區號}

參數

參數類型必填說明
zipcodestring是3/5/6 位郵遞區號
formatstring否3+2 或 3+3（3碼查詢時使用，預設 3+2）
pagenumber否頁碼（預設 1）
limitnumber否每頁筆數（預設 100，最大 500）

範例請求

bash
curl "https://ziptw.com/api/reverse?zipcode=100"

範例回應

json
{
  "zipcode": "100",
  "total": 156,
  "page": 1,
  "limit": 100,
  "results": [
    {
      "zipcode": "10058",
      "city": "臺北市",
      "district": "中正區",
      "road": "八德路１段",
      "scope": "全"
    }
  ]
}

錯誤處理 ​

所有錯誤回應都遵循統一格式：

json
{
  "error": "錯誤類型",
  "message": "錯誤說明"
}

HTTP 狀態碼 ​

狀態碼說明
200成功
400參數錯誤
405不支援的 HTTP 方法
429超過速率限制
500伺服器內部錯誤

速率限制 ​

API 回應標頭中包含速率限制資訊：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
  • 免費使用：每 IP 每天 100 次請求
  • 超過限制時將回傳 429 狀態碼

使用範例 ​

JavaScript / Node.js ​

javascript
const response = await fetch(
  'https://ziptw.com/api/zipcode?address=' +
  encodeURIComponent('台北市中正區重慶南路一段122號')
)
const data = await response.json()
console.log(data.zipcode_32) // "10045"

Python ​

python
import requests

response = requests.get(
    'https://ziptw.com/api/zipcode',
    params={'address': '台北市中正區重慶南路一段122號'}
)
data = response.json()
print(data['zipcode_32'])  # "10045"

PHP ​

php
$address = urlencode('台北市中正區重慶南路一段122號');
$response = file_get_contents("https://ziptw.com/api/zipcode?address={$address}");
$data = json_decode($response, true);
echo $data['zipcode_32']; // "10045"

注意事項 ​

  • API 僅支援 GET 請求
  • 地址參數請使用 URL 編碼
  • 建議在客戶端快取查詢結果以減少 API 呼叫
  • API 支援 CORS，可直接從瀏覽器端呼叫

Copyright © 2024 郵遞區號隨手查 All rights reserved.