知乎日報 API 分析(如何規範api設計)
宣告
以下所有 API 均由 知乎(Zhihu.Inc) 提供,本人(Xiao Liang)採取非正常手段獲取。獲取與共享之行為或有侵犯知乎權益的嫌疑。若被告知需停止共享與使用,本人會及時刪除此頁面與整個專案。
請您暸解相關情況,並遵守知乎協議。
API 說明
-
知乎日報的訊息以 JSON 格式輸出
-
網址中
api
後數字代表 API 版本,過高或過低均會得到錯誤資訊 -
較老的介面(啟動介面影象獲取,最新訊息,過往訊息)中將數字 2 替換為 1.2 獲得效果相同,替換為 1.1 獲得的是老版本 API 輸出的 JSON 格式(替換為更低,如 1.0,或更高,如 1.3,將會獲得錯誤訊息)
-
以下所有 API 使用的 HTTP Method 均為
GET
-
所有的連結均使用
HTTPS
API 分析
1. 啟動介面影象獲取
-
URL:
https://news-at.zhihu.com/api/7/prefetch-launch-images/1080*1920
-
該 API 似乎已經停止使用。最新版本的 App 在啟動時並無 Splash Screen,App 將直接顯示日報內容或彈出廣告。
-
prefetch-launch-images
後為影象解析度,接受任意的number*number
格式,number
為任意非負整數,返回值均相同。 -
響應例項:
{ "creatives": [ { "url": "https://pic3.zhimg.com/v2-5af460972557190bd4306ad66f360d4a.jpg", "start_time": 1491927091, "impression_tracks": [ "https://sugar.zhihu.com/track?vs=1&ai=3838&ut=&cg=2&ts=1491927091.68&si=52848dcc42b046bbb2d7a40921268157&lu=0&hn=ad-engine.ad-engine.7fab952b&at=impression&pf=PC&az=11&sg=4590d6230fc8f471ada5f10e6f27be94" ], "type": 0, "id": "3838" } ] }
- 分析:
url
: 影象的 URLstart_time
: 獲取的時間(ms)
2. 軟體版本查詢
-
Android:
https://news-at.zhihu.com/api/4/version/android/2.3.0
-
iOS:
https://news-at.zhihu.com/api/4/version/ios/2.3.0
-
URL 最後部分的數字代表所安裝『知乎日報』的版本
-
響應例項:
軟體為最新版本時
{ "status": 0, "latest": "2.2.0" }
軟體為較老版本時
{ "status": 1, "msg": "【更新內容】(後略)", "latest": "2.2.0" }
-
分析:
status
: 0 代表軟體為最新版本,1 代表軟體需要升級latest
: 軟體最新版本的版本號(數字的第二段會比最新的版本號低 1)msg
: 僅出現在軟體需要升級的情形下,提示使用者升級軟體的對話方塊中顯示的訊息
3. 最新訊息
-
URL:
https://news-at.zhihu.com/api/4/news/latest
-
響應例項:
{ date: "20140523", stories: [ { title: "中國古代傢俱發展到今天有兩個高峰,一個兩宋一個明末(多圖)", ga_prefix: "052321", images: [ "http://p1.zhimg.com/45/b9/45b9f057fc1957ed2c946814342c0f02.jpg" ], type: 0, id: 3930445 }, ... ], top_stories: [ { title: "商場和很多人家裡,竹製傢俱越來越多(多圖)", image: "http://p2.zhimg.com/9a/15/9a1570bb9e5fa53ae9fb9269a56ee019.jpg", ga_prefix: "052315", type: 0, id: 3930883 }, ... ] }
-
分析:
date
: 日期stories
: 當日新聞title
: 新聞標題images
: 影象地址(官方 API 使用陣列形式。目前暫未有使用多張圖片的情形出現,曾見無images
屬性的情況,請在使用中注意 )ga_prefix
: 供 Google Analytics 使用type
: 作用未知id
:url
與share_url
中最後的數字(應為內容的 id)multipic
: 訊息是否包含多張圖片(僅出現在包含多圖的新聞中)
top_stories
: 介面頂部 ViewPager 滾動顯示的顯示內容(子項格式同上)(請注意區分此處的image
屬性與stories
中的images
屬性)
4. 訊息內容獲取與離線下載
-
URL:
https://news-at.zhihu.com/api/4/news/3892357
-
使用在
最新訊息
中獲得的id
,拼接在https://news-at.zhihu.com/api/4/news/
後,得到對應訊息 JSON 格式的內容 -
響應例項:
{ body: "<div class="main-wrap content-wrap">...</div>", image_source: "Yestone.com 版權圖片庫", title: "深夜驚奇 · 朋友圈錯覺", image: "http://pic3.zhimg.com/2d41a1d1ebf37fb699795e78db76b5c2.jpg", share_url: "http://daily.zhihu.com/story/4772126", js: [ ], recommenders": [ { "avatar": "http://pic2.zhimg.com/fcb7039c1_m.jpg" }, { "avatar": "http://pic1.zhimg.com/29191527c_m.jpg" }, { "avatar": "http://pic4.zhimg.com/e6637a38d22475432c76e6c9e46336fb_m.jpg" }, { "avatar": "http://pic1.zhimg.com/bd751e76463e94aa10c7ed2529738314_m.jpg" }, { "avatar": "http://pic1.zhimg.com/4766e0648_m.jpg" } ], ga_prefix: "050615", section": { "thumbnail": "http://pic4.zhimg.com/6a1ddebda9e8899811c4c169b92c35b3.jpg", "id": 1, "name": "深夜驚奇" }, type: 0, id: 4772126, css: [ "http://news.at.zhihu.com/css/news_qa.auto.css?v=1edab" ] }
-
分析:
body
: HTML 格式的新聞image-source
: 圖片的內容提供方。為了避免被起訴非法使用圖片,在顯示圖片時最好附上其版權資訊。title
: 新聞標題image
: 獲得的圖片同最新訊息
獲得的圖片解析度不同。這裡獲得的是在文章瀏覽介面中使用的大圖。share_url
: 供線上檢視內容與分享至 SNS 用的 URLjs
: 供手機端的 WebView(UIWebView) 使用recommenders
: 這篇文章的推薦者ga_prefix
: 供 Google Analytics 使用section
: 欄目的資訊thumbnail
: 欄目的縮圖id
: 該欄目的id
name
: 該欄目的名稱
type
: 新聞的型別id
: 新聞的 idcss
: 供手機端的 WebView(UIWebView) 使用- 可知,知乎日報的文章瀏覽介面利用 WebView(UIWebView) 實現
-
特別注意
在較為特殊的情況下,知乎日報可能將某個主題日報的站外文章推送至知乎日報首頁。
響應例項:{ "theme_name": "電影日報", "title": "五分鐘讀懂明星的花樣暱稱:一美、法鯊……", "share_url": "http://daily.zhihu.com/story/3942319", "js": [], "ga_prefix": "052921", "editor_name": "鄒波", "theme_id": 3, "type": 1, "id": 3942319, "css": [ "http://news.at.zhihu.com/css/news_qa.6.css?v=b390f" ] }
此時返回的 JSON 資料缺少
body
,image-source
,image
,js
屬性。多出theme_name
,editor_name
,theme_id
三個屬性。type
由0
變為1
。
5. 過往訊息
-
URL:
https://news-at.zhihu.com/api/4/news/before/20131119
-
若果需要查詢 11 月 18 日的訊息,
before
後的數字應為20131119
-
知乎日報的生日為 2013 年 5 月 19 日,若
before
後數字小於20130520
,只會接收到空訊息 -
輸入的今日之後的日期仍然獲得今日內容,但是格式不同於最新訊息的 JSON 格式
-
響應例項:
{ date: "20131118", stories: [ { title: "深夜食堂 · 我的張曼妮", ga_prefix: "111822", images: [ "http://p4.zhimg.com/7b/c8/7bc8ef5947b069513c51e4b9521b5c82.jpg" ], type: 0, id: 1747159 }, ... ] }
-
格式與前同,恕不再贅述
6. 新聞額外資訊
-
URL:
https://news-at.zhihu.com/api/4/story-extra/#{id}
-
輸入新聞的ID,獲取對應新聞的額外資訊,如評論數量,所獲的『贊』的數量。
-
響應例項:
{ "long_comments": 0, "popularity": 161, "short_comments": 19, "comments": 19, }
-
分析:
long_comments
: 長評論總數popularity
: 點贊總數short_comments
: 短評論總數comments
: 評論總數
7. 新聞對應長評論檢視
-
URL:
https://news-at.zhihu.com/api/4/story/8997528/long-comments
-
使用在
最新訊息
中獲得的id
,在https://news-at.zhihu.com/api/4/story/#{id}/long-comments
中將id
替換為對應的id
,得到長評論 JSON 格式的內容 -
響應例項:
{ "comments": [ { "author":"巨型黑娃兒", "content":"也不算邏輯問題。其實小時候剛剛聽說這個玩意的時候我也奇...", "avatar":"http://pic3.zhimg.com/4131a3385c748c9e2d02ab80e29a0c52_im.jpg", "time":1479706360, "reply_to":{ "content":"第二個機靈抖的還是有邏輯問題,不該說忘了,應該說沒喝過啊我也不知道", "status":0, "id":27275308, "author":"2233155495" }, "id":27276057, "likes":2 }, ... ] }
-
分析:
comments
: 長評論列表,形式為陣列(請注意,其長度可能為 0)author
: 評論作者content
: 評論的內容avatar
: 使用者頭像圖片的地址id
: 評論者的唯一識別符號likes
: 評論所獲『贊』的數量time
: 評論時間reply_to
: 所回覆的訊息content
: 原訊息的內容status
: 訊息狀態,0為正常,非0為已被刪除id
: 被回覆者的唯一識別符號author
: 被回覆者err_msg
: 錯誤訊息,僅當status
非0時出現
8. 新聞對應短評論檢視
-
URL:
https://news-at.zhihu.com/api/4/story/4232852/short-comments
-
使用在
最新訊息
中獲得的id
,在https://news-at.zhihu.com/api/4/story/#{id}/short-comments
中將id
替換為對應的id
,得到短評論 JSON 格式的內容 -
響應例項:
{ "comments": [ { "author": "Xiaole說", "id": 545721, "content": "就吃了個花生米,呵呵", "likes": 0, "time": 1413600071, "avatar": "http://pic1.zhimg.com/c41f035ab_im.jpg" }, ... ] }
-
格式與前同,恕不再贅述
9. 主題日報列表檢視
-
URL:
https://news-at.zhihu.com/api/4/themes
-
響應例項:
{ "limit": 1000, "subscribed": [ ], "others": [ { "color": 8307764, "thumbnail": "http://pic4.zhimg.com/2c38a96e84b5cc8331a901920a87ea71.jpg", "description": "內容由知乎使用者推薦,海納主題百萬,趣味上天入地", "id": 12, "name": "使用者推薦日報" }, ... ] }
- 分析:
limit
: 返回數目之限制(僅為猜測)subscribed
: 已訂閱條目others
: 其他條目color
: 顏色,作用未知thumbnail
: 供顯示的圖片地址description
: 主題日報的介紹id
: 該主題日報的編號name
: 供顯示的主題日報名稱
- 分析:
10. 主題日報內容檢視
-
URL:
https://news-at.zhihu.com/api/4/theme/11
-
使用在
主題日報列表檢視
中獲得需要檢視的主題日報的id
,拼接在https://news-at.zhihu.com/api/4/theme/
後,得到對應主題日報 JSON 格式的內容 -
響應例項:
{ stories: [ { images: [ "http://pic1.zhimg.com/84dadf360399e0de406c133153fc4ab8_t.jpg" ], type: 0, id: 4239728, title: "前蘇聯監獄紋身百科圖鑑" }, ... ], description: "為你發現最有趣的新鮮事,建議在 WiFi 下檢視", background: "http://pic1.zhimg.com/a5128188ed788005ad50840a42079c41.jpg", color: 8307764, name: "不許無聊", image: "http://pic3.zhimg.com/da1fcaf6a02d1223d130d5b106e828b9.jpg", editors: [ { url: "http://www.zhihu.com/people/wezeit", bio: "微在 Wezeit 主編", id: 70, avatar: "http://pic4.zhimg.com/068311926_m.jpg", name: "益康糯米" }, ... ], image_source: "" }
- 分析:
stories
: 該主題日報中的文章列表images
: 影象地址(其型別為陣列。請留意在程式碼中處理無該屬性與陣列長度為 0 的情況)type
: 型別,作用未知title
: 訊息的標題
description
: 該主題日報的介紹background
: 該主題日報的背景圖片(大圖)color
: 顏色,作用未知name
: 該主題日報的名稱image
: 背景圖片的小圖版本editors
: 該主題日報的編輯(『使用者推薦日報』中此項的指是一個空陣列,在 App 中的主編欄顯示為『許多人』,點選後訪問該主題日報的介紹頁面,請留意)url
: 主編的知乎使用者主頁bio
: 主編的個人簡介id
: 資料庫中的唯一表示符avatar
: 主編的頭像name
: 主編的姓名
image_source
: 影象的版權資訊
- 分析:
11. 熱門訊息
-
請注意! 此 API 仍可訪問,但是其內容未出現在最新的『知乎日報』 App 中。
-
URL:
https://news-at.zhihu.com/api/3/news/hot
-
響應例項:
{ recent: [ { news_id: 3748552, url: "http://daily.zhihu.com/api/2/news/3748552", thumbnail: "http://p3.zhimg.com/67/6a/676a8337efec71a100eea6130482091b.jpg", title: "長得漂亮能力出眾性格單純的姑娘為什麼會沒有男朋友?" }, ... ] }
-
大體同前面介紹的 API 類似,唯一需要注意的是:欲獲得圖片地址,不再使用
image
而是thumbnail
屬性 -
url
屬性可直接使用。請注意,url
中的api
屬性為 2,是較老版本。
12. 軟體推廣
- 請注意! 此 API 已無法訪問,但是其內容曾出現於『知乎日報』 App 中。
- Android:
http://news-at.zhihu.com/api/3/promotion/android
- iOS:
http://news-at.zhihu.com/api/3/promotion/ios
13. 欄目總覽
-
請注意! 此 API 仍可訪問,但是其內容未出現在最新的『知乎日報』 App 中。
-
URL:
http://news-at.zhihu.com/api/3/sections
-
響應例項:
{ data: [ { id: 1, thumbnail: "http://p2.zhimg.com/10/b8/10b8193dd6a3404d31b2c50e1e232c87.jpg", name: "深夜食堂", description: "睡前宵夜,用別人的故事下酒" }, ... ] }
-
同樣,注意使用
thumbnail
獲取影象的地址
14. 欄目具體訊息檢視
-
請注意! 此 API 仍可訪問,但是其內容未出現在最新的『知乎日報』 App 中。
-
URL:
http://news-at.zhihu.com/api/3/section/1
-
URL 最後的數字見『欄目總覽』中相應欄目的
id
屬性 -
響應例項:
{ news: [ { date: "20140522", display_date: "5 月 22 日" }, ... ], name: "深夜食堂", timestamp: 1398780001 }
-
往前:
http://news-at.zhihu.com/api/3/section/1/before/1398780001
- 在 URL 最後加上一個時間戳,時間戳詳見 JSON 資料末端的
timestamp
屬性
- 在 URL 最後加上一個時間戳,時間戳詳見 JSON 資料末端的
15. 檢視新聞的推薦者
-
URL:
https://news-at.zhihu.com/api/4/story/#{id}/recommenders
-
將新聞id填入到#{id}的位置, 如
https://news-at.zhihu.com/api/4/story/7101963/recommenders
-
響應例項
{ "items": [], "editors": [{ "bio": "樹上的女爵", "title": "主編", "id": 79, "avatar": "http:\/\/pic1.zhimg.com\/0a6456810_m.jpg", "name": "劉柯" }], "item_count": 1 }
16. 獲取某個專欄之前的新聞
-
URL:
https://news-at.zhihu.com/api/4/section/#{section id}/before/#{timestamp}
-
將專欄id填入到 #{section id}, 將時間戳填入到#{timestamp},如
https://news-at.zhihu.com/api/4/section/34/before/1465772400
-
注:新聞id要是屬於該專欄,否則,返回結果為空
-
響應例項:
{ "stories": [ { "images": [ "http://pic2.zhimg.com/27f3d8f4c1e0000d04ee446a2f020cf1_t.jpg" ], "type": 2, "id": 7119477, "title": "9 張本週最熱節操圖,諾一就是人生贏家本人" }, ... ] }
17. 檢視 Editor 的主頁
- iOS:
https://news-at.zhihu.com/api/4/editor/#{id}/profile-page/ios
- Android:
https://news-at.zhihu.com/api/4/editor/#{id}/profile-page/android