freshrss/google-reader-api-zh/api
api_get| modified | Friday 7 February 2025 |
|---|
!!! info
- 所有调用都应在 cookie 中包含 SID(对于 TTRSS 和 FreshRSS 实现,应在请求的 header 中增加"Authorization": GoogleLogin auth={auth})
- 所有查询类操作都应包含 T token (&T=) (推荐全部传入以防止错误)
- 除另有说明外,请求地址均为 ~/reader/api/0/ ,如freshrss.example.net/api/greader.php/reader/api/0/
- 推荐保留client参数以示不同客户端的区分(&client=)(作为params传入)
- GReader 及其实现将 feed 的 URL 作为其 feed ID,将帖子的 Atom entry ID 作为其 post ID
- 在 GReader 及其实现中,文件夹实际上是标签(或 GReader 术语中的 “标签”),这意味着同一 feed 可以存在于多个文件夹中
- 所有调用都接受一个 ck=[timestamp] 参数,根据Google Reader API 文档的解释,该参数是 “当前的时间戳,可能是用来确保缓存不会被触发的快捷方式”。
!!! Note
在示例代码中,使用的是同时兼容原版 Google Reader API 和 FreshAPI 的传参方法 (即同时传入 SID 和 header) 同时均包含了 t token
Endpoint:subscription/list
Method:GET
params参数:
| 参数名 | 必选 | 示例值 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|---|
| output | 是 | json/xml |
xml |
string | 选择输出的格式 |
用法示例:
=== “Curl”
```bash
curl -s -H 'Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8' -H 'Cookie: SID=YOUR_SID' \
'https://freshrss.example.net/api/greader.php/reader/api/0/subscription/list?output=json&client=myclient&T=YOUR_T_TOKEN'
```
=== “Python”
```python
import requests
url = 'https://freshrss.example.net/api/greader.php/reader/api/0/subscription/list'
header = {
"Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8"
}
params = {
'output': 'json',
'client': 'myclient',
'T': 'YOUR_T_TOKEN'
}
cookies = {'SID': 'YOUR_SID'}
try:
response = requests.get(url, headers=header, params=params, cookies=cookies)
response.raise_for_status()
print(response.text)
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
```
当 output=xml时,返回样例如下
1<object>
2<string name="id">feed/http://feeds.feedburner.com/NickBradbury</string>
3<string name="title">Nick Bradbury</string>
4<list name="categories">
5<object>
6<string name="id">user/[USER_ID]/label/Bradbury Software</string>
7<string name="label">Bradbury Software</string>
8</object>
9</list>
10<string name="sortid">C430EC8F</string>
11<number name="firstitemmsec">1203460831522</number>
12</object>
当output=json时,返回样例如下
1{
2 "subscriptions": [{
3 "id": "feed/39",
4 "title": "标题测试1",
5 "categories": [{
6 "id": "user/-/label/Uncategorized",
7 "label": "Uncategorized"
8 }],
9 "url": "https://example.com",
10 "htmlUrl": "https://example-html.com",
11 "iconUrl": "http://example/public.php?op=feed_icon&id=39.ico"
12 }, {
13 "id": "feed/31",
14 "title": "标题测试2",
15 "categories": [{
16 "id": "user/-/label/分类测试1",
17 "label": "分类测试1"
18 }],
19 "url": "https://example.com",
20 "htmlUrl": "https://example-html.com",
21 "iconUrl": "http://example/public.php?op=feed_icon&id=31.ico"
22 }, {
23 "id": "feed/30",
24 "title": "标题测试3",
25 "categories": [{
26 "id": "user/-/label/分类测试1",
27 "label": "分类测试1"
28 }],
29 "url": "https://example.com",
30 "htmlUrl": "https://example-html.com",
31 "iconUrl": "http://example/public.php?op=feed_icon&id=30.ico"
32 }]
33}
!!! info
文件夹的名称以 节点中。 根文件夹中的馈送有一个空的
节点。 firstitemmsec 属性是该用户订阅中最旧(第一个)项目的时间戳。
更简单的方法是以 GET 方法调用 `subscriptions/export` 以 获取OPML文件的导出 ,但这不包括任何 GReader 数据(如 firstitemmsec)。
**注意:** 请求参数中的 `/` 需要进行 URL 编码,例如 `/` 编码为 `%2F`。
**注意:** 除非传入feed参数(s参数),否则操作会失败。(无法创建空文件夹,必须创建有订阅源的文件夹)
Endpoint:unread-count
Method:GET
params参数:
| 参数名 | 必选 | 示例值 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|---|
| output | 是 | xml/json |
xml |
string | 指定返回格式为XML |
用法示例:
=== “Curl”
```bash
curl -s -H 'Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8' -H 'Cookie: SID=YOUR_SID' \
'https://freshrss.example.net/api/greader.php/reader/api/0/unread-count?output=json&client=myclient&T=YOUR_T_TOKEN'
```
=== “Python”
```python
import requests
url = 'https://freshrss.example.net/api/greader.php/reader/api/0/unread-count'
header = {
"Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8"
}
params = {
'output': 'json',
'client': 'myclient',
'T': 'YOUR_T_TOKEN'
}
cookies = {'SID': 'YOUR_SID'}
try:
response = requests.get(url, headers=header, params=params, cookies=cookies)
response.raise_for_status()
print(response.text)
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
```
如果存在未读条目,返回xml样例如下
1<object>
2 <number name="max">1000</number>
3 <list name="unreadcounts">
4 <object>
5 <string name="id">user/-/state/com.google/reading-list</string>
6 <number name="count">8</number>
7 <number name="newestItemTimestampUsec">1232641608774062</number>
8 </object>
9 <object>
10 <string name="id">feed/http://rss.cnn.com/rss/cnn_topstories.rss</string>
11 <number name="count">4</number>
12 <number name="newestItemTimestampUsec">1232641203555343</number>
13 </object>
14 <object>
15 <string name="id">user/-/label/FolderName</string>
16 <number name="count">8</number>
17 <number name="newestItemTimestampUsec">1232641608774062</number>
18 </object>
19 <object>
20 <string name="id">feed/http://www.engadget.com/rss.xml</string>
21 <number name="count">4</number>
22 <number name="newestItemTimestampUsec">1232641608774062</number>
23 </object>
24</list>
25</object>
返回json样例如下
1{
2 "max": 8
3 "unreadcounts": [
4 {
5 "id": "user/-/state/com.google/reading-list",
6 "count": 8,
7 "newestItemTimestampUsec": "1232641608774062"
8 },
9 {
10 "id": "feed/http://rss.cnn.com/rss/cnn_topstories.rss",
11 "count": 4,
12 "newestItemTimestampUsec": "1232641203555343"
13 },
14 {
15 "id": "user/-/label/FolderName",
16 "count": 8,
17 "newestItemTimestampUsec": "1232641608774062"
18 },
19 {
20 "id": "feed/http://www.engadget.com/rss.xml",
21 "count": 4,
22 "newestItemTimestampUsec": "1232641608774062"
23 }
24 ...
25 ]
26}
如果不存在未读条目,返回xml样例如下
1<object>
2 <number name="max">1000</number>
3 <list name="unreadcounts"/>
4</object>
返回`json``样例如下
1{
2 "max": 1000,
3 "unreadcounts": []
4}
Endpoint:stream/contents/user/-/state/com.google/reading-list
Method:GET
params参数:
| 参数名 | 必选 | 示例值 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|---|
| n | 否 | 20 | 20 | number | 请求最大条数,最大为1000 |
| r | 否 | o / n | o | string | 排序方式。o 表示按文章发布时间倒序排列(旧->新), n 表示按文章更新时间倒序排列(新->旧) |
| t | 否 | 1678886400 | 无 | number | 获取比指定时间戳更新的文章(Unix时间戳,毫秒) |
| ot | 否 | 1678886400 | 无 | number | 获取比指定时间戳更旧的文章(Unix时间戳,毫秒) |
| xt | 否 | user/-/state/com.google/read | 无 | string | 排除标签,示例为排除已读内容 |
| c | 否 | continuation string | 无 | string | 续读的字符串,用于分页加载更多条目 |
| output | 是 | xml/json | json | string | 输出样例,默认为json |
用法示例:
=== “Curl”
```bash
curl -s -H 'Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8' -H 'Cookie: SID=YOUR_SID' \
'https://freshrss.example.net/api/greader.php/reader/api/0/stream/contents/user/-/state/com.google/reading-list?n=20&r=o&ot=1678886400&xt=user/-/state/com.google/read&output=json&client=myclient&T=YOUR_T_TOKEN'
```
=== “Python”
```python
import requests
url = 'https://freshrss.example.net/api/greader.php/reader/api/0/stream/contents/user/-/state/com.google/reading-list'
header = {
"Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8"
}
params = {
'n': 20,
'r': 'o',
'ot': 1678886400,
'xt': 'user/-/state/com.google/read',
'output': 'json',
'client': 'myclient',
'T': 'YOUR_T_TOKEN'
}
cookies = {'SID': 'YOUR_SID'}
try:
response = requests.get(url, headers=header, params=params, cookies=cookies)
response.raise_for_status()
print(response.text)
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
```
返回样例:
Endpoint:user-info
Method:GET
参数:无
用法示例:
=== “Curl”
```bash
curl -s -H 'Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8' -H 'Cookie: SID=YOUR_SID' \
'https://freshrss.example.net/api/greader.php/reader/api/0/user-info?T=YOUR_T_TOKEN'
```
=== “Python”
```python
import requests
url = 'https://freshrss.example.net/api/greader.php/reader/api/0/user-info'
header = {
"Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8"
}
params ={
'T': 'YOUR_T_TOKEN'
}
cookies = {'SID': 'YOUR_SID'}
try:
response = requests.get(url, headers=header, params=params, cookies=cookies)
response.raise_for_status()
print(response.text)
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
```
返回样例:
1{
2 "userId":"admin",
3 "userName":"admin",
4 "userProfileId":"admin",
5 "userEmail":""
6}
Endpoint:friend/list
Method:GET
参数:无
用法示例:
=== “Curl”
```bash
curl -s -H 'Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8' -H 'Cookie: SID=YOUR_SID' \
'https://freshrss.example.net/api/greader.php/reader/api/0/friend/list&T=YOUR_T_TOKEN'
```
=== “Python”
```python
import requests
url = 'https://freshrss.example.net/api/greader.php/reader/api/0/friend/list'
header = {
"Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8"
}
params ={
'T': 'YOUR_T_TOKEN'
}
cookies = {'SID': 'YOUR_SID'}
try:
response = requests.get(url, headers=header, params=params, cookies=cookies)
response.raise_for_status()
print(response.text)
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
```
Endpoint:preference/list
Method:GET
参数:无
用法示例:
=== “Curl”
```bash
curl -s -H 'Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8' -H 'Cookie: SID=YOUR_SID' \
'https://freshrss.example.net/api/greader.php/reader/api/0/preference/list&T=YOUR_T_TOKEN'
```
=== “Python”
```python
import requests
url = 'https://freshrss.example.net/api/greader.php/reader/api/0/preference/list'
header = {
"Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8"
}
params ={
'T': 'YOUR_T_TOKEN'
}
cookies = {'SID': 'YOUR_SID'}
try:
response = requests.get(url, headers=header, params=params, cookies=cookies)
response.raise_for_status()
print(response.text)
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
```
Endpoint:preference/list/stream/contents/user/-/state/com.google/starred
Method:GET
parmas参数:
| 参数名 | 必选 | 示例值 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|---|
| n | 是 | 20 | 无 | number | 获取星标文章的数量,最大为1000 |
| output | 否 | json/xml | json | string | 指定返回格式为json或者xml |
用法示例:
=== “Curl”
```bash
curl -s -H 'Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8' -H 'Cookie: SID=YOUR_SID' \
'https://freshrss.example.net/api/greader.php/reader/api/0/stream/contents/user/-/state/com.google/starred?n=20&output=json&client=myclient&T=YOUR_T_TOKEN'
```
=== “Python”
```python
import requests
url = 'https://freshrss.example.net/api/greader.php/reader/api/0/stream/contents/user/-/state/com.google/starred'
header = {
"Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8"
}
params = {
'n': 20,
'output': 'json',
'client': 'myclient',
'T': 'YOUR_T_TOKEN'
}
cookies = {'SID': 'YOUR_SID'}
try:
response = requests.get(url, headers=header, params=params, cookies=cookies)
response.raise_for_status()
print(response.text)
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
```
返回样例
1{
2 "id": "user/-/state/com.google/reading-list",
3 "updated": 1738469151,
4 "items": [
5 {
6 "id": "tag:google.com,2005:reader/item/000000000001035c",
7 "crawlTimeMsec": "1738411626000",
8 "timestampUsec": "1738411626000000",
9 "published": 1738411626,
10 "title": "...",
11 "canonical": [
12 {
13 "href": "...""
14 }
15 ],
16 "alternate": [
17 {
18 "href": "...""
19 }
20 ],
21 "categories": [
22 "user/-/state/com.google/read",
23 "user/-/state/com.google/starred"
24 ],
25 "origin": {
26 "streamId": "feed/31",
27 "title": "..."",
28 "htmlUrl": "...""
29 },
30 "summary": {
31 "content": "...""
32 },
33 "author": ""
34 }
35 ],
36 "continuation": "1"
37}
Endpoint:/atom/feed/{feed_url}
Method:GET
parmas参数:
| 参数名 | 必选 | 示例值 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|---|
| feed_url | 是 | http://feeds.feedburner.com/Ni… | 无 | string | 欲解析的RSS链接 |
| n | 否 | 40 | 20 | number | 加载文章条目的数量 |
| xt | 否 | user/-/state/com.google/read | 无 | string | 排除的标签 |
用法示例:
=== “Curl”
```bash
curl -s -H 'Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8' -H 'Cookie: SID=YOUR_SID' \
'https://freshrss.example.net/api/greader.php/reader/api/0/atom/feed/http://feeds.feedburner.com/NickBradbury?n=40&xt=user/-/state/com.google/read&client=myclient&T=YOUR_T_TOKEN'
```
=== “Python”
```python
import requests
url = 'https://freshrss.example.net/api/greader.php/reader/api/0/atom/feed/http://feeds.feedburner.com/NickBradbury'
header = {
"Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8"
}
params = {
'n': 40,
'xt': 'user/-/state/com.google/read',
'client': 'myclient',
'T': 'YOUR_T_TOKEN'
}
cookies = {'SID': 'YOUR_SID'}
try:
response = requests.get(url, headers=header, params=params, cookies=cookies)
response.raise_for_status()
print(response.text)
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
```
返回样例:
1<entry>
2 <id>tag:google.com,2005:reader/item/30fd6c8e007ebcbf</id>
3 <published>2009-01-03T18:37:04Z</published>
4 <updated>2009-01-03T18:37:04Z</updated>
5 <title>[Article summary]</title>
6 <content type="html">[Article content]</content>
7 <author>
8 <name>Nick Bradbury</name>
9 </author>
10 <link rel="alternate" href="http://example.com/article" />
11 <category scheme="http://www.google.com/reader/atom" term="tag:google.com,2005:reader/feed/http://feeds.feedburner.com/NickBradbury" />
12 <gr:crawl-timestamp-msec>1233716224000</gr:crawl-timestamp-msec> <!-- Unix timestamp -->
13 <gr:is-read-state-locked>true</gr:is-read-state-locked> <!-- 如果条目被锁定为未读 -->
14</entry>
!!! note
gr:crawl-timestamp-msec 表示 Google Reader 接收文章的 Unix 时间戳 (毫秒)。
**`gr:is-read-state-locked="true"`**: 如果条目的阅读状态被锁定 ("保持未读"),则会包含此属性。
**`<id>`**条目的值始终为 Google Reader 中的 ID,用以替换订阅源中的原始 GUID/ID。 原始 GUID/ID 仍可从 ID 节点获取,例如:
`<id gr:original-id="http://nick.typepad.com/blog/2009/01/">tag:google.com,2005:reader/item/30fd6c8e007ebcbf</id>`
**`Categories`** 不仅用于反映实际信息源中为该条目分配的类别,还用于反映 GReader 中的已读/标记状态。
* 如果一篇文章已被阅读,它的**`Categories`**会如下所示:
* ```<category term="user/[userid]/state/com.google/read" scheme="http://www.google.com/reader/" label="read" />```
* 如果一篇文章已被标星,它的**`Categories`**会如下所示:
* ```<category term="user/[userid]/state/com.google/starred" scheme="http://www.google.com/reader/" label="starred"/> ```
* 如果一篇文章在文件夹内,它的**`Categories`**会如下所示
* ```<category term="user/[userid]/label/[folderName]" scheme="http://www.google.com/reader/" label="[folderName]"/> ```
Google Reader (GReader) 获取订阅源的一个重要部分是**续读(continuation)**功能,它提供了一种分页浏览订阅源条目(entries)的方法。例如,如果您请求订阅源中最新的 20 条条目,根元素可能包含一个 **gr:continuation**子元素,例如:
1<feed xmlns:gr="http://www.google.com/schemas/reader/atom/" xmlns="http://www.w3.org/2005/Atom">
2 <generator uri="http://www.google.com/reader">Google Reader</generator>
3 <id>tag:google.com,2005:reader/feed/http://feeds.feedburner.com/NickBradburyClippings</id>
4 <title>Nick Bradbury&#39;s Shared Items on NewsGator Online</title>
5 <updated>2009-01-15T15:17:16Z</updated>
6<gr:continuation>CP__hN2fq5gC</gr:continuation>
只需将 gr:continuation 值附加到后续请求中,即可获取订阅源中的接下来的 20 个条目,例如:
GET http://www.google.com/reader/a…
这使得访问订阅源的历史记录成为可能,这在订阅订阅源后或用户首次选择启用 GReader 同步时可能立即有用。
!!!info
对于自部署RSS阅读器,共享项目可能是无用且不被支持的,故不是所有API兼容实现都可以调用该API
Endpoint:/reader/atom/user/-/state/com.google/broadcast&n={count}
Method:GET
parmas参数:
| 参数名 | 必选 | 示例值 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|---|
| {count} | 是 | 20 | 无 | number | 欲获取用户共享文章的数量 |
用法示例:
=== “Curl”
```bash
curl -s -H 'Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8' -H 'Cookie: SID=YOUR_SID' \
'https://freshrss.example.net/api/greader.php/reader/api/0/reader/atom/user/-/state/com.google/broadcast?n=20&client=myclient&T=YOUR_T_TOKEN'
```
=== “Python”
```python
import requests
url = 'https://freshrss.example.net/api/greader.php/reader/api/0/reader/atom/user/-/state/com.google/broadcast'
header = {
"Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8"
}
params = {
'n': 20,
'client': 'myclient',
'T': 'YOUR_T_TOKEN'
}
cookies = {'SID': 'YOUR_SID'}
try:
response = requests.get(url, headers=header, params=params, cookies=cookies)
response.raise_for_status()
print(response.text)
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
```
!!!note
- 需要注意的是,条目 ID 必须是 GReader 中条目的 ID,因此来自非 GReader 源的条目需要像任意 URL 一样共享,例如:
- POST item/edit?share=true&title={title}&url={url}&snippet={snippet}&srcTitle="{srcTitle}"&srcUrl={srcUr}。
- 再次检索用户的共享项目时,您会看到 GReader 已为此项目分配了一个条目 ID。sourceTitle 和 srcUrl 参数分别是项目来源页面/源的名称和链接。还可以添加 annotation 参数。在已添加批注的共享项目条目(“带笔记共享”)中,将会包含类似这样的内容
Endpoint:tag/list
Method:GET
parmas参数:
| 参数名 | 必选 | 示例值 | 默认值 | 类型 | 说明 |
|---|---|---|---|---|---|
| output | 是 | xml/json | 无 | string | 输出的格式 |
用法示例:
=== “Curl”
```bash
curl -s -H 'Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8' -H 'Cookie: SID=YOUR_SID' \
'https://freshrss.example.net/api/greader.php/reader/api/0/tag/list?output=json&client=myclient&T=YOUR_T_TOKEN'
```
=== “Python”
```python
import requests
url = 'https://freshrss.example.net/api/greader.php/reader/api/0/tag/list'
header = {
"Authorization: GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8"
}
params = {
'output': "json",
'client': 'myclient',
'T': 'YOUR_T_TOKEN'
}
cookies = {'SID': 'YOUR_SID'}
try:
response = requests.get(url, headers=header, params=params, cookies=cookies)
response.raise_for_status()
print(response.text)
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}")
如果output=json,返回样例如下:
1{
2 "tags": [{
3 "id": "user/-/state/com.google/starred"
4 }, {
5 "id": "user/-/label/A",
6 "type": "folder"
7 }, {
8 "id": "user/-/label/B",
9 "type": "folder"
10 }, {
11 "id": "user/-/label/C",
12 "type": "folder"
13 }, {
14 "id": "user/-/label/D",
15 "type": "folder"
16 }, {
17 "id": "user/-/label/E",
18 "type": "folder"
19 }, {
20 "id": "user/-/label/F",
21 "type": "tag"
22 }, {
23 "id": "user/-/label/G",
24 "type": "folder"
25 }, {
26 "id": "user/-/label/H",
27 "type": "tag"
28 }, {
29 "id": "user/-/label/I",
30 "type": "folder"
31 }, {
32 "id": "user/-/label/J",
33 "type": "folder"
34 }, {
35 "id": "user/-/label/K",
36 "type": "folder"
37 }, {
38 "id": "user/-/label/L",
39 "type": "tag"
40 }, {
41 "id": "user/-/label/Uncategorized",
42 "type": "folder"
43 }, {
44 "id": "user/-/label/测试",
45 "type": "tag"
46 }]
47}
!!! note
由于 Google Reader 将文件夹视为标签,因此此列表将包含文件夹名称。客户端需要自行解析出实际的文件夹名称标签。