AIRUN · 開發者文件

AEO 掃描 API

給一個網址，回傳這個網站對 AI 答案引擎（ChatGPT、Claude、Perplexity、Gemini）的友善度：總分、四維度分數、18 項指標逐項結果，以及照優先順序排好的修復清單。免金鑰，可直接從瀏覽器、腳本或你的 AI agent 呼叫。

GEThttps://airun.tw/api/aeo-scan?url=example.com

人類版工具在 airun.tw/aeo，背後呼叫的就是這支 API。機器可讀的能力清單在 /.well-known/agents.json。

參數

名稱	位置	必填	說明
`url`	query	是	要掃的網站。可以帶 `https://`，也可以只給網域（`example.com`）。內網位址不掃。

怎麼評分

程式會抓首頁，再抽查幾頁內頁（回應裡的 pages_scanned），逐項做確定性查核：有沒有、格式對不對、內容夠不夠。同一個網站在內容沒變的情況下，每次結果一樣。評分過程沒有用語言模型，不會有編造的判斷。

維度	滿分	查什麼
A 抓取與收錄基礎	25	robots.txt 是否放行 AI 爬蟲、sitemap.xml、llms.txt、canonical 與語言標記
B 結構化資料	30	JSON-LD 類型覆蓋、Organization 完整度、Open Graph、Title 與 Description 品質
C 內容可答性	30	標題層級、FAQ／問答、清單與表格、可讀文字量、新鮮度訊號、內頁健康抽查
D 實體與信任	15	聯絡資訊、關於／公司頁、社群連結（sameAs）、行動裝置支援

評級：90 分以上 A（AI 友善）、75 以上 B（良好）、60 以上 C（及格待補）、40 以上 D（弱）、40 以下 E（幾乎不可見）。

回應

成功時回 200，內容是 JSON。以下是掃 airun.tw 的真實回應（節錄）：

{
  "url": "https://airun.tw",
  "reachable": true,
  "scanned_at": "2026-10-11T04:25:10.719Z",
  "score": 80,
  "grade": "B（良好）",
  "dimScores": [
    { "dim": "A", "name": "抓取與收錄基礎", "got": 25, "max": 25 },
    { "dim": "B", "name": "結構化資料", "got": 25, "max": 30 },
    { "dim": "C", "name": "內容可答性", "got": 25, "max": 30 },
    { "dim": "D", "name": "實體與信任", "got": 5, "max": 15 }
  ],
  "breakdown": [
    { "dim": "A", "key": "robots.txt＋AI 爬蟲放行", "got": 8, "max": 8, "note": "有，且放行 AI 爬蟲" }
    // …共 18 項
  ],
  "fixes": [
    {
      "dim": "D", "key": "聯絡資訊", "priority": 2, "effort": "30 分鐘",
      "why": "AI 推薦在地服務時會確認「這是真實存在的公司嗎」……",
      "how": "頁尾放公司全名、電話、地址、Email，並同步進 Organization schema……"
    }
  ],
  "pages_scanned": 5,
  "site": { "name": "AIRUN", "description": "…", "sameAs": [], "phone": "", "email": "…" }
}

欄位	型別	說明
`url`	string	實際掃描的網址（已正規化）
`reachable`	boolean	首頁抓不抓得到。`false` 時分數只反映抓得到的部分，請先確認網站可公開連線
`scanned_at`	string	掃描時間（ISO 8601，UTC）
`score`	number	總分 0–100
`grade`	string	評級 A–E，括號內是中文說明
`dimScores`	array	四個維度各自的得分 `got` 與滿分 `max`
`breakdown`	array	18 項指標逐項：所屬維度、項目名、得分、滿分、查核說明 `note`
`fixes`	array	沒拿滿分的項目，依 `priority` 排序（1 最優先），附 `why` 原因、`how` 做法、`effort` 預估工時
`pages_scanned`	number	實際抓了幾頁（首頁加內頁抽查）
`site`	object	從網站結構化資料讀到的實體資訊：名稱、描述、sameAs、電話、Email

錯誤

狀態碼	什麼時候	回應
`400`	沒給 `url`，或格式不像網址	`{"error":"請提供有效網址，例如 ?url=example.com"}`
`429`	同一個 IP 一分鐘超過 6 次	`{"error":"掃描太頻繁，請一分鐘後再試"}`
`502`	目標網站連不上或掃描中途失敗	`{"error":"掃描失敗，可能是目標網站無法連線","detail":"…"}`

限制與快取

頻率：每個 IP 每分鐘 6 次。一次掃描會對目標網站發出最多 6 個請求，限流也是為了不替任何人代掃別人的網站。
快取：成功回應帶 Cache-Control: public, max-age=600。同一個網址 10 分鐘內重掃，可能拿到快取結果。
CORS：回應帶 Access-Control-Allow-Origin: *，網頁前端可以直接呼叫。
耗時：通常幾秒到二十幾秒，看目標網站的速度。請把逾時設在 60 秒以上。

我們記錄什麼

每次成功掃描，我們會記下：時間、掃描的網址、總分、評級、修復項數量。用途是統計整體網站的 AI 友善度。我們不記錄呼叫者的身分，也不需要你提供 Email。

範例

curl

curl -s "https://airun.tw/api/aeo-scan?url=example.com" | jq '{score, grade, fixes: [.fixes[].key]}'

JavaScript

const r = await fetch("https://airun.tw/api/aeo-scan?url=" + encodeURIComponent("example.com"));
if (!r.ok) throw new Error((await r.json()).error);
const scan = await r.json();
console.log(scan.score, scan.grade);
for (const f of scan.fixes) console.log(`[P${f.priority}] ${f.key}：${f.how}`);

Python

import requests

r = requests.get("https://airun.tw/api/aeo-scan", params={"url": "example.com"}, timeout=90)
r.raise_for_status()
scan = r.json()
print(scan["score"], scan["grade"])
for f in scan["fixes"]:
    print(f"[P{f['priority']}] {f['key']}：{f['how']}")

給 AI agent 的用法

如果你在寫會幫人改網站的 agent：先呼叫這支 API 拿 fixes，照 priority 由小到大處理，每項的 how 就是具體做法。改完再掃一次，比對 score 和 breakdown，確認那一項真的拿到分數。

這份文件也有機器版：網址加 ?format=md，或請求時帶 Accept: text/markdown。