法律搜尋

法律文件搜尋

透過 GET /api/v1/search 端點， 對法律資料庫執行關鍵字、語意或混合搜尋，回傳依相關性排序的法律文件列表。

端點

GEThttps://developer-api.lawbot.tw/api/v1/search

認證方式與 Chat API 相同：Authorization: Bearer YOUR_API_KEY

搜尋模式

keyword關鍵字搜尋

Elasticsearch 全文檢索，支援 A & B AND 多關鍵字語法，適合查詢特定法條條號、判決字號或精確詞彙。回傳結果的 content 為含 <em> 標籤的高亮 HTML 片段。

semantic語意搜尋

向量語意搜尋 + Rerank，理解自然語言問句的語意，適合「駕車過失傷人如何求償」等問句形式查詢。

hybrid混合搜尋（推薦）

關鍵字與語意並行搜尋後經 Rerank 排序，兼顧精確比對與語意理解，適合大多數場景，為預設推薦模式。

Query 參數

參數名稱型別必填說明
querystring是搜尋字串，長度 1–500 字元。keyword 模式支援 A & B AND 語法；semantic 模式建議輸入完整自然語言問句。
search_typekeyword | semantic | hybrid否搜尋模式，預設 keyword。keyword = 全文檢索；semantic = 語意搜尋；hybrid = 混合（推薦）。
limitinteger否最多回傳幾筆結果，範圍 1–50，預設 10。

cURL 範例

關鍵字搜尋（keyword）

terminal
curl -G "https://developer-api.lawbot.tw/api/v1/search" \
  --data-urlencode "query=勞動基準法" \
  -d "search_type=keyword&limit=10" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

語意搜尋（semantic）

terminal
curl -G "https://developer-api.lawbot.tw/api/v1/search" \
  --data-urlencode "query=駕車過失傷人如何求償" \
  -d "search_type=semantic&limit=5" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

混合搜尋（hybrid，推薦）

terminal
curl -G "https://developer-api.lawbot.tw/api/v1/search" \
  --data-urlencode "query=股東會決議瑕疵" \
  -d "search_type=hybrid&limit=10" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

回應格式（SearchResponse）

search_response.json
{
  "documents": [
    {
      "doc_id": "law-civil-123",
      "title": "民法第 191-3 條",
      "content": "從事...工作...之人，對於他人之損害，應負賠償責任。",
      "doc_type": "法規命令",
      "is_abandoned": false,
      "url": "/laws/civil/191-3"
    },
    {
      "doc_id": "verdict-taipei-456",
      "title": "臺灣臺北地方法院 113 年交簡字第 100 號",
      "content": "被告駕駛自用小客車，因疏未注意...",
      "doc_type": "裁判",
      "is_abandoned": false,
      "url": "/verdicts/taipei/113-交簡-100"
    }
  ],
  "search_type": "hybrid"
}

DocumentResponse 欄位說明

欄位型別說明
doc_idstring文件唯一識別碼（必有）。
titlestring | null文件標題，例如法條名稱或判決案號。
contentstring | null文件內文
doc_typeDocumentType | null文件類型：憲法法庭裁判 / 釋字 / 函釋 / 法規命令 / 裁判。
is_abandonedboolean是否為已廢止或失效文件，預設 false。
urlstring | null文件詳細頁面的相對 URL 路徑。

Python 搜尋範例

search.py
import os
import requests

API_KEY = os.environ.get("LAWBOT_API_KEY")
BASE_URL = "https://developer-api.lawbot.tw"

headers = {"Authorization": f"Bearer {API_KEY}"}

# 混合搜尋（推薦）
response = requests.get(
    f"{BASE_URL}/api/v1/search",
    headers=headers,
    params={
        "query": "股東會決議瑕疵的法律效果",
        "search_type": "hybrid",
        "limit": 10,
    },
)

data = response.json()
print(f"搜尋模式：{data['search_type']}")
print(f"找到 {len(data['documents'])} 筆結果\n")

for doc in data["documents"]:
    abandoned = "（已廢止）" if doc.get("is_abandoned") else ""
    print(f"[{doc.get('doc_type', '未知')}] {doc['title']}{abandoned}")
    if doc.get("content"):
        # keyword 模式的 content 可能含 HTML 高亮標籤
        print(f"  {doc['content'][:100]}...")
    print()

Node.js / TypeScript 搜尋範例

search.ts
import fetch from "node-fetch";

const API_KEY = process.env.LAWBOT_API_KEY!;
const BASE_URL = "https://developer-api.lawbot.tw";

async function searchDocumentsAsync(
  query: string,
  searchType: "keyword" | "semantic" | "hybrid" = "hybrid",
  limit = 10,
) {
  const params = new URLSearchParams({
    query,
    search_type: searchType,
    limit: String(limit),
  });

  const response = await fetch(`${BASE_URL}/api/v1/search?${params}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });

  if (!response.ok) {
    throw new Error(`Search failed: ${response.status}`);
  }

  return response.json() as Promise<SearchResponse>;
}

// 使用範例
const result = await searchDocumentsAsync("消費者保護法無條件退貨", "semantic");
console.log(`實際搜尋模式：${result.search_type}`);
result.documents.forEach((doc) => {
  console.log(`[${doc.doc_type}] ${doc.title}`);
});

錯誤碼說明

狀態碼說明
401Bearer Token 無效、已撤銷或過期。
422參數格式錯誤：query 為空或超過 500 字元、limit 不在 1–50 範圍、search_type 非法值。
429Lifetime 搜尋次數已達上限（lifetime_limit_exceeded）。
500搜尋引擎（Elasticsearch / Upstash）或 Rerank 服務異常。