seo-api

Sitemap 變化

GET/api/v1/sitemap/changesMCP get_sitemap_changes前 3 個網域免費，超出每個 2 點/天

監控任意網站的 sitemap，每天拿到它新增和下線的頁面。

端點

  • GET

    路徑/api/v1/sitemap/watches

    作用列出監控的網域，含狀態、是否免費和最近一次掃描。

  • POST

    路徑/api/v1/sitemap/watches

    作用新增監控。請求內容 { "domain": "example.com" }，重複新增不會報錯。

  • DELETE

    路徑/api/v1/sitemap/watches?domain=

    作用停止監控，既有的變化紀錄保留。

  • GET

    路徑/api/v1/sitemap/changes?domain=

    作用新增或下線的頁面 URL，依日期倒序。

  • GET

    路徑/api/v1/sitemap/history?domain=&days=

    作用每天的頁面數和新增、下線數。

運作方式

  • 每個監控的網域每天台北時間 9 點左右抓一次，入口是 robots.txt 裡的 Sitemap: 宣告（沒有就用 /sitemap.xml）。
  • 第一次抓取只記錄頁面清單，第二天起才回報變化。
  • 近 30 天沒出現過的頁面算新增；連續 7 天沒出現的頁面算下線。
  • 頁面總數不到基準的七成時，這一天標記為 suspicious，不判定下線；部分 sitemap 檔案抓取失敗時（complete: false）同樣不判定下線。
  • 只能查自己監控的網域。www.example.com 和 example.com 是兩個站。

請求參數

  • domain

    型別string

    必填是

    說明你監控的網域。

  • date

    型別string

    必填—

    說明指定一天，YYYY-MM-DD（台北時間）。不傳就看最近 30 天。

  • change

    型別string

    必填—

    說明added 或 removed，不傳兩種都要。

  • scope

    型別string

    必填—

    說明primary（預設）不含 /de/ 這類語言前綴下的翻譯頁；all 全部包含。

  • page

    型別integer

    必填—

    說明頁碼，從 1 開始。

  • pageSize

    型別integer

    必填—

    說明每頁筆數，1–200，預設 50。

請求範例

shell
# Watch a domain (crawled daily from tomorrow 09:00 UTC+8)
curl -X POST "https://seo-api.org/api/v1/sitemap/watches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

# Pages it added in the last 30 days
curl "https://seo-api.org/api/v1/sitemap/changes?domain=example.com&change=added" \
  -H "Authorization: Bearer YOUR_API_KEY"

回應範例

items 每列是一筆 URL 變化：snapshotDate、change、url、section（第一層目錄）和 locale；total 是符合條件的總筆數。

200 OK
{
  "ok": true,
  "data": {
    "items": [
      {
        "snapshotDate": "2026-10-29",
        "domain": "example.com",
        "change": "added",
        "url": "https://example.com/tools/new-tool",
        "section": "tools",
        "locale": null
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 50
  }
}

計費

查詢不扣點數。監控的前 3 個網域（依新增時間最早的算）免費；超出的每個網域，每天掃描成功扣 2 點數。建立基準的那天和掃描失敗的日子不扣。點數不足時超出的網域會暫停，餘額夠扣一天後自動恢復。

錯誤碼

  • SEO_API.MISSING_API_KEY

    HTTP401

    含義沒有 Authorization 標頭，也沒有 x-api-key 標頭。

  • SEO_API.INVALID_API_KEY

    HTTP401

    含義key 不存在或已被撤銷。

  • SEO_API.INVALID_DOMAIN

    HTTP400

    含義缺少 domain 參數，或者它不是網域（IP 會被拒絕）。

  • BILLING.INSUFFICIENT_CREDITS

    HTTP402

    含義帳號點數用完了。24 小時內的重複查詢仍然可用。

  • SYSTEM.INTERNAL_SERVER_ERROR

    HTTP500

    含義我們這邊出了問題，請稍候再重試。

透過 MCP 呼叫

工具 list_sitemap_watches、add_sitemap_watch、remove_sitemap_watch、get_sitemap_changes 和 get_sitemap_history，參數與 REST 一致。

tools/call
{
  "name": "get_sitemap_changes",
  "arguments": {
    "domain": "example.com",
    "change": "added"
  }
}

透過命令列呼叫

terminal
npx @seo-api/cli sitemap add example.com
npx @seo-api/cli sitemap list
npx @seo-api/cli sitemap changes example.com --added

其他 API