文件 / API 參考

API 參考

SEOLens REST API 的完整參考。

基礎 URL

https://seo-lens.site/api/v1

認證

所有 API 請求都需要 API 金鑰。登入控制台建立免費 API 金鑰。透過 Authorization 標頭或 x-api-key 標頭將金鑰包含在每個請求中。

Authorization: Bearer YOUR_API_KEY

# or

x-api-key: YOUR_API_KEY

POST

/research

研究一個或多個關鍵字，取得搜尋量、難度、CPC 數據和相關關鍵字推薦。

請求主體

參數	類型	必填	說明
keyword	string	Yes*	要研究的單一關鍵字
keywords	string[]	Yes*	關鍵字陣列（最多 50 個）。用來取代： `keyword`
countryCode	string	No	國家代碼（預設："US"）。選項：US, JP, GB, DE, FR, CA, AU, BR, IN, KR, MX, ES, IT, NL, SE, TW, TH, VN, ID, PH
languageCode	string	No	語言代碼（預設："en"）。選項：en, ja, de, fr, es, pt, it, nl, ko, zh, th, vi, id, sv

* 請提供以下其一： keyword 或 keywords（不可同時使用）。

回應格式（單一關鍵字）

200 OK

{
  "keyword": "react hooks",
  "metrics": {
    "avgMonthlySearches": 18100,
    "competition": "LOW",
    "cpcLow": 0.15,
    "cpcHigh": 1.85
  },
  "difficulty": "easy",
  "suggestions": [
    {
      "keyword": "react custom hooks",
      "avgMonthlySearches": 6600,
      "competition": "LOW",
      "cpcLow": 0.10,
      "cpcHigh": 0.95
    }
  ]
}

回應格式（批次）

200 OK

{
  "results": [
    {
      "keyword": "react hooks",
      "metrics": { ... },
      "difficulty": "easy",
      "suggestions": [ ... ]
    },
    {
      "keyword": "vue composables",
      "metrics": { ... },
      "difficulty": "medium",
      "suggestions": [ ... ]
    }
  ]
}

程式碼範例

JavaScript / TypeScript

fetch

const response = await fetch("https://seo-lens.site/api/v1/research", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    keywords: ["nextjs seo"],
    countryCode: "US",
    languageCode: "en",
  }),
});

const data = await response.json();
console.log(data.results);

Python

requests

import requests

response = requests.post(
    "https://seo-lens.site/api/v1/research",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "keywords": ["nextjs seo"],
        "countryCode": "US",
        "languageCode": "en",
    },
)

data = response.json()
print(f"Results: {data['results']}")

cURL

bash

# Single keyword
curl -X POST https://seo-lens.site/api/v1/research \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"keywords": ["nextjs seo"], "countryCode": "US"}'

# Batch keywords
curl -X POST https://seo-lens.site/api/v1/research \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"keywords": ["react hooks", "vue composables"], "countryCode": "US"}'

錯誤代碼

狀態	說明
200	成功 - 已返回關鍵字數據
401	未授權 - API 金鑰缺失或無效
400	錯誤請求 - 參數缺失或無效
429	超過速率限制 - 請求過多
500	內部伺服器錯誤 - 請稍後重試

速率限制

免費方案設有速率限制，以確保所有用戶的公平使用。

每個 IP 位址每日 100 次請求
每次批次請求 50 個關鍵字
已快取的結果不計入速率限制