{"openapi":"3.1.0","info":{"title":"流量觀察 API","version":"1","description":"台灣網站每月的 Similarweb 造訪估算、搜尋與 AI 導流、Cloudflare Radar 排名與標籤彙整。造訪量單位為百萬次，占比為 0–1。"},"servers":[{"url":"https://traffic.observe.tw"}],"paths":{"/api/v1/months":{"get":{"operationId":"months","tags":["排行"],"summary":"有流量資料的月份","parameters":[],"responses":{"200":{"description":"有流量資料的月份","content":{"application/json":{"schema":{"type":"object","properties":{"months":{"type":"array","description":"string[]：YYYYMM，新到舊"}}}}}}}}},"/api/v1/rankings":{"get":{"operationId":"rankings","tags":["排行"],"summary":"單一月份的網站排行","description":"依造訪量由大到小。topic、exclude、source 可同時使用；名次在篩選後剩下的網站之間重新計算。沒有 Similarweb 估算的月份用 Pro 補登或試算表數字，visitsSource 會註明。","parameters":[{"name":"month","in":"query","required":false,"description":"資料月份；不在資料範圍內時改用最新月份","schema":{"type":"string"}},{"name":"topic","in":"query","required":false,"description":"只列出有這個標籤的網站","schema":{"type":"string"}},{"name":"exclude","in":"query","required":false,"description":"排除有這些標籤的網站，以逗號分隔（例如 非台灣,內容農場）；API 不套網頁的預設排除","schema":{"type":"string"}},{"name":"source","in":"query","required":false,"description":"只列出某個追蹤來源的網域；manual 包含試算表與手動加入","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"比較月份：成長、前期名次與各占比的前期值都和它比較","schema":{"type":"string","default":"前一個有資料的月份"}}],"responses":{"200":{"description":"單一月份的網站排行","content":{"application/json":{"schema":{"type":"object","properties":{"month":{"type":"string","description":"string (YYYYMM)：實際使用的月份"},"topic":{"type":"string","description":"string | null"},"exclude":{"type":"array","description":"string[]：實際排除的標籤（不存在的標籤會被略過）"},"source":{"type":"string","description":"string | null"},"topics":{"type":"array","description":"object[]：這個月份（套用 source 後、排除前）各標籤的網站數"},"sites":{"type":"array","description":"object[]：排行"}}}}}}}}},"/api/v1/rankings.csv":{"get":{"operationId":"rankings-csv","tags":["排行"],"summary":"同上，以 CSV 下載","description":"UTF-8（含 BOM），欄位：名次、網站名、網域、原表標籤 A、標籤、流量(百萬)、成長、上月名次、搜尋S、AI、搜尋占比、AI占比、台灣占比、來源。","parameters":[{"name":"month","in":"query","required":false,"description":"資料月份；不在資料範圍內時改用最新月份","schema":{"type":"string"}},{"name":"topic","in":"query","required":false,"description":"只列出有這個標籤的網站","schema":{"type":"string"}},{"name":"exclude","in":"query","required":false,"description":"排除有這些標籤的網站，以逗號分隔（例如 非台灣,內容農場）；API 不套網頁的預設排除","schema":{"type":"string"}},{"name":"source","in":"query","required":false,"description":"只列出某個追蹤來源的網域；manual 包含試算表與手動加入","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"比較月份：成長、前期名次與各占比的前期值都和它比較","schema":{"type":"string","default":"前一個有資料的月份"}}],"responses":{"200":{"description":"同上，以 CSV 下載","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/api/v1/history":{"get":{"operationId":"history","tags":["歷史與網站"],"summary":"所有月份、所有網站的造訪量，一次取得","description":"首頁就是讀這一份資料。每個網站、每個月是一個五格陣列，欄位意義見 fields。回應約數 MB，快取 5 分鐘。","parameters":[],"responses":{"200":{"description":"所有月份、所有網站的造訪量，一次取得","content":{"application/json":{"schema":{"type":"object","properties":{"generatedAt":{"type":"string","description":"string (ISO 時間)"},"months":{"type":"array","description":"string[]：YYYYMM，舊到新"},"fields":{"type":"array","description":"string[]：每月陣列的欄位：造訪量、搜尋S、AI（百萬次）、台灣占比、來源（0 Similarweb、1 試算表、2 平台補登）"},"topics":{"type":"array","description":"string[]：所有用到的標籤"},"sources":{"type":"array","description":"object[]：各追蹤來源的網域數（tag、blog、manual）"},"sites":{"type":"object","description":"object：以網域為鍵"},"radar":{"type":"object","description":"object：以網域為鍵的 Cloudflare Radar 排名，舊到新"}}}}}}}}},"/api/v1/sites/{domain}":{"get":{"operationId":"site","tags":["歷史與網站"],"summary":"單一網站的每月數字、試算表紀錄與抓取狀態","description":"每個月分開列出 Similarweb、平台補登與試算表三種數字；網站頁用的就是這一份。沒有任何資料的網域回 404。","parameters":[{"name":"domain","in":"path","required":true,"description":"網域，例如 udn.com","schema":{"type":"string"}}],"responses":{"200":{"description":"單一網站的每月數字、試算表紀錄與抓取狀態","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"string"},"name":{"type":"string","description":"string"},"topics":{"type":"array","description":"string[]"},"months":{"type":"array","description":"object[]：舊到新"},"labels":{"type":"array","description":"object[]：試算表原始紀錄：month、name、group（A 欄）、topics（B 欄）、visits、adjusted（人工調整，不採用）"},"profile":{"type":"object","description":"object | null：Similarweb 最新一個有估算的月份的組成：month、countries（前 5 名 code、share）、channels（Direct、SearchOrganic、SearchPaid、SocialOrganic、SocialPaid、Referrals、Mail、DisplayAds、GenAi、Affiliate 的占比）、bounceRate、pagesPerVisit、timeOnSite（秒）、globalRank、countryRank、categoryRank"},"category":{"type":"string","description":"string | null：Similarweb 的網站類別，例如 Finance/Investing"},"similarSites":{"type":"array","description":"string[]：Similarweb 列出的相似網站"},"tags":{"type":"array","description":"object[]：每個標籤的來源與票數，同 /api/v1/tags/{domain}"},"watchers":{"type":"array","description":"object[]：追蹤這個網域的來源：requester、kind、requestedAt"},"radar":{"type":"array","description":"object[]：Cloudflare Radar：dateStart、dateEnd、rank、bucket、bucketLowerBound、fetchedAt"},"state":{"type":"object","description":"object | null：Similarweb 抓取狀態：lastSuccessAt、lastAttemptAt、nextAttemptAt、failures、lastError"}}}}}},"404":{"description":"{\"error\": \"...\"}"}}}},"/api/v1/tags/{domain}":{"get":{"operationId":"site-tags","tags":["標籤"],"summary":"單一網站的每個標籤、來源與投票數","description":"包含未顯示的標籤。編輯清單（或試算表）的標籤一律顯示；AI 初判在不同意比同意多 2 票時隱藏；讀者新增的標籤在同意多於不同意時顯示；管理員覆寫優先。只回票數，不回投票者。未知網域回 404。","parameters":[{"name":"domain","in":"path","required":true,"description":"網域，例如 udn.com","schema":{"type":"string"}}],"responses":{"200":{"description":"單一網站的每個標籤、來源與投票數","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"string"},"tags":{"type":"array","description":"object[]：顯示中的在前"}}}}}},"404":{"description":"{\"error\": \"...\"}"}}}},"/api/v1/tech":{"get":{"operationId":"tech","tags":["網站技術"],"summary":"各網站首頁偵測到的技術與統計","description":"範圍是所有追蹤清單與試算表的網域。每個首頁約一個月檢查一次，比對 Wappalyzer 社群版規則中本站列出的技術；「unknown」表示首頁沒有清單內技術的痕跡，不代表沒有技術。technologies 依 source 篩選後計算，sites 再依 category、technology、status 篩選。","parameters":[{"name":"source","in":"query","required":false,"description":"只看某個追蹤來源的網域","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"只列出有這類技術的網站，例如 cms、cdn、analytics、ads","schema":{"type":"string"}},{"name":"technology","in":"query","required":false,"description":"只列出用這項技術的網站，例如 wordpress","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"只列出最近一次是這個結果的網站","schema":{"type":"string"}}],"responses":{"200":{"description":"各網站首頁偵測到的技術與統計","content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"type":"string","description":"string | null：目前的規則版本（wappalyzer-<commit 前 12 碼>）"},"coverage":{"type":"object","description":"object：sites、checked、withSnapshot（有成功結果）、detected、unknown、failed、blocked"}}}}}}}}},"/api/v1/tech/{domain}":{"get":{"operationId":"tech-domain","tags":["網站技術"],"summary":"單一網域的技術偵測結果、依據與檢查紀錄","description":"任何檢查過的網域都有，包括有人在 /tech/ 查詢、不在追蹤清單裡的網域。沒檢查過回 404。","parameters":[{"name":"domain","in":"path","required":true,"description":"網域，例如 udn.com","schema":{"type":"string"}}],"responses":{"200":{"description":"單一網域的技術偵測結果、依據與檢查紀錄","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"\"detected\" | \"unknown\" | \"failed\" | \"blocked\"：最近一次檢查的結果"},"errorCode":{"type":"string","description":"string | null"},"httpStatus":{"type":"integer","description":"integer | null"},"lastAttemptAt":{"type":"string","description":"string"},"observedAt":{"type":"string","description":"string | null"},"sourceUrl":{"type":"string","description":"string | null：讀到的頁面（轉址後，去掉查詢字串）"},"ruleVersion":{"type":"string","description":"string | null"},"origin":{"type":"string","description":"\"traffic\" | \"blog\""}}}}}},"404":{"description":"{\"error\": \"...\"}"}}}},"/api/v1/topics/all":{"get":{"operationId":"topics-all","tags":["標籤"],"summary":"跨月份的標籤彙整","description":"以網站目前的標籤彙整所有已知月份；同一網域在一個標籤內只算一次。指定 topic 時另附該標籤的完整網站清單；不存在的標籤回 404。","parameters":[{"name":"topic","in":"query","required":false,"description":"加上這個標籤的網站清單","schema":{"type":"string"}}],"responses":{"200":{"description":"跨月份的標籤彙整","content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","description":"\"all\""},"months":{"type":"array","description":"string[]：有流量資料的月份"},"topics":{"type":"array","description":"object[]：依累計造訪量排序"},"topic":{"type":"string","description":"string：指定 topic 時才有"},"sites":{"type":"array","description":"object[]：指定 topic 時才有：domain、name、topics、months（有資料月數）、visits、searchShare、aiShare"}}}}}},"404":{"description":"{\"error\": \"...\"}"}}}},"/api/v1/topics":{"get":{"operationId":"topics-month","tags":["標籤"],"summary":"單一月份的標籤統計與成長","description":"舊版介面，保留給既有使用者；新的使用方式請用 /api/v1/topics/all。","parameters":[{"name":"month","in":"query","required":false,"description":"資料月份；不在資料範圍內時改用最新月份","schema":{"type":"string"}}],"responses":{"200":{"description":"單一月份的標籤統計與成長","content":{"application/json":{"schema":{"type":"object","properties":{"month":{"type":"string","description":"string (YYYYMM)"}}}}}}}}},"/icon/{domain}":{"get":{"operationId":"icon","tags":["歷史與網站"],"summary":"網站圖示（64×64 PNG）","description":"只回應本站已知的網域；圖示由伺服器向 Google favicon 服務抓取並快取 30 天。沒有圖示時回 404。","parameters":[{"name":"domain","in":"path","required":true,"description":"網域","schema":{"type":"string"}}],"responses":{"200":{"description":"網站圖示（64×64 PNG）","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"{\"error\": \"...\"}"}}}},"/api/v1/status":{"get":{"operationId":"status","tags":["抓取與服務"],"summary":"Similarweb 抓取排程與最近批次","description":"抓取狀態頁用的資料。每小時一輪，每輪最多 budget 個網域。","parameters":[],"responses":{"200":{"description":"Similarweb 抓取排程與最近批次","content":{"application/json":{"schema":{"type":"object","properties":{"budget":{"type":"integer","description":"integer：每輪上限"},"priority":{"type":"array","description":"string[]：來源的優先序"},"coolingDownUntil":{"type":"string","description":"string (ISO 時間) | null：被 Similarweb 拒絕後暫停到何時"},"watched":{"type":"integer","description":"integer：追蹤中的網域數"},"due":{"type":"integer","description":"integer：目前到期的網域數"},"queue":{"type":"array","description":"object[]：排程：domain、position、requester、reason（new、refresh、catch-up、lookup）、lastSuccessAt、expectedAt"},"watchers":{"type":"array","description":"object[]：各來源與類型的網域數：requester、kind、domains"},"last24h":{"type":"object","description":"object：近 24 小時的請求結果計數"},"runs":{"type":"array","description":"object[]：最近批次：startedAt、finishedAt、budget、sent、ok、failed、refused、note"}}}}}}}}},"/api/v1":{"get":{"operationId":"index","tags":["抓取與服務"],"summary":"端點索引（JSON）","parameters":[],"responses":{"200":{"description":"端點索引（JSON）","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","description":"string"},"docs":{"type":"string","description":"string：這份文件的網址"},"openapi":{"type":"string","description":"string：OpenAPI 規格的網址"},"endpoints":{"type":"object","description":"object：「方法 路徑」對應用途"}}}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"openapi","tags":["抓取與服務"],"summary":"OpenAPI 3.1 規格","parameters":[],"responses":{"200":{"description":"OpenAPI 3.1 規格","content":{"application/json":{"schema":{"type":"object","properties":{}}}}}}}}}}