今日诗词 API 是一个可以返回一句古诗词名句的接口。它可以通过图片和 JSON 格式调用。今日诗词 API 根据不同地点、时间、节日、季节、天气、景观、城市进行智能推荐。

如果您不以我们的接口及其提供的内容盈利,您可以免费的使用我们的 API。使用我们的API代表您同意了我们的 使用协议

1. 我应该选择哪个调用方式?

为了提高推荐的效果,请您正确选择调用方式。
原则上,为了获取到正确的 IP 定位信息,我们的接口都不应在服务端调用。

2. 图片形式调用

one

图片调用地址为:

https://v2.jinrishici.com/one.svg

Markdown 格式

![今日诗词](https://v2.jinrishici.com/one.svg)

HTML 格式

<img alt="今日诗词" src="https://v2.jinrishici.com/one.svg">

HTML 调用时在所在 DIV 居中并且不会 overflow :

<img alt="今日诗词" src="https://v2.jinrishici.com/one.svg" style="max-width:100%; display: block; margin: 0 auto;">

如果您需要自定义图片的文字的大小、间距、颜色,可以在图片地址后面加参数:

参数名
说明
默认值
合法范围
font-size
字体大小(px)
20
[8,50]
spacing
间距(px)
1.5
[0,30]
color
颜色
black
颜色英文单词

例如:

https://v2.jinrishici.com/one.svg?font-size=20&spacing=2&color=blue

需要注意的是,颜色目前只接收英文单词, 查看所有颜色英文单词

图片调用形式仅限在浏览器环境中调用。

另外,掘金等一些网站或论坛,会在后端保存图片并替换地址,请注意识别。

3. 网站快速安装

为了方便您的调用,我们特意开发了一款 JS-SDK 供您快速部署。这款SDK帮您完成了 标准 JSON 接口 的所有步骤。

浏览器能直接打开的网站才能使用本方法部署

简单版 :在 HTML 中需要加载诗词的地方放置以下加载代码即可:

<span id="jinrishici-sentence">正在加载今日诗词....</span>
<script src="https://sdk.jinrishici.com/v2/browser/jinrishici.js" charset="utf-8"></script>

SDK 会自动寻找 id 或者 classjinrishici-sentence 的标签,将里面的内容替换为诗词
如果需要在多个地方显示诗词,添加多个 class=" jinrishici-sentence " 的 span 即可

高级版:如果你有其他需求(如获取作者、朝代等),可以调用我们提供的加载函数 jinrishici.load 并传入回调函数,每调用一次,会传入一个新的诗词

<script src="https://sdk.jinrishici.com/v2/browser/api.js" charset="utf-8"></script>
<script type="text/javascript">
  jinrishici.load(function(result) {
    // 自己的处理逻辑
    console.log(result)
  });
</script>
result 的 格式见 返回结果
出错我们会帮你打在控制台上,您无需再次处理。
使用定制加载时,不要将标签的 id 或者 class 设置为 jinrishici-sentence ,否则SDK会自动加载一次
使用 load 之前,请确保 SDK JS 文件已经引入

4. 小程序快速安装

如果您使用微信小程序调用我们的接口,我们也为您准备了SDK。这款SDK帮您实现了 JSON-TOKEN 接口 的所有步骤

第二步,放置在您的小程序目录,一般是 /utils 下

第三步,在微信后台添加我们的API地址到白名单:

https://v2.jinrishici.com

第四步,在您需要调用的 Page 的 JS 文件最上面,引用我们的SDK

const jinrishici = require('../../utils/jinrishici.js')
请注意文件夹深度,确保文件地址正确。

第五步,在 JS 文件的 onLoad 处 或者其他地方,调用我们的加载函数,您需要传一个回调函数。

jinrishici.load(result => {
  // 下面是处理逻辑示例
  console.log(result)
  this.setData({"jinrishici": result.data.content})
})

result 的格式见 返回结果

大功告成!

5. 标准 JSON 接口

标准 JSON 接口是用于前端调用的通用接口,它的原理是向用户发送 Cookies 鉴别每个用户,Cookies 中携带 Token 。如果您是移动端、客户端、桌面端,请使用 JSON-TOKEN 接口

如果您是后端调用,请参见 服务端调用

网站快速安装 已经实现了浏览器端的JDK,如果仍然不能满足您的需求,您可以使用本接口自行发送请求

5.1. API接口

API的地址为(无参数,GET方法,前端调用请务必使 withCredentials = true

https://v2.jinrishici.com/one.json
请注意,为了正确保存 Cookies ,务必使 withCredentials = true 并确保您的配置正确,您可以用 接口测试 工具验证,我们会对没有配置的情况进行惩罚。 见 使用协议

原生JS调用示例:

<script>
  var xhr = new XMLHttpRequest();
  xhr.open('get', 'https://v2.jinrishici.com/one.json');
  xhr.withCredentials = true;
  xhr.onreadystatechange = function () {
    if (xhr.readyState === 4) {
      var data = JSON.parse(xhr.responseText);
      // 处理示例
      var gushici = document.getElementById('gushici');
      gushici.innerText = data.data.content;
    }
  };
  xhr.send();
</script>

axios 调用示例

const jinrishici = axios.create({
  baseURL: "https://v2.jinrishici.com/one.json",
  withCredentials: true
})

jinrishici.get('').then(function (response) {
    console.log(response.data);
})

Jquery 调用示例:

$.ajax({
  url: 'https://v2.jinrishici.com/one.json',
  xhrFields: {
     withCredentials: true
  },
  success: function (result, status) {
    console.log(result)
  }
});

5.2. 返回结果

正确返回:

{
    "status": "success",
    "data": {
        "id": "5b8b9572e116fb3714e6faba",
        "content": "君问归期未有期,巴山夜雨涨秋池。",
        "popularity": 1170000,
        "origin": {
            "title": "夜雨寄北",
            "dynasty": "唐代",
            "author": "李商隐",
            "content": [
                "君问归期未有期,巴山夜雨涨秋池。",
                "何当共剪西窗烛,却话巴山夜雨时。"
            ],
            "translate": [
                "您问归期,归期实难说准,巴山连夜暴雨,涨满秋池。",
                "何时归去,共剪西窗烛花,当面诉说,巴山夜雨况味。"
            ]
        },
        "matchTags": [
            "秋",
            "晚上"
        ],
        "recommendedReason": "",
        "cacheAt": "2018-09-17T21:18:44.693645"
    },
    "token": "6453911a-9ad7-457e-9b9d-c21011b85a0c",
    "ipAddress": "162.248.93.154"
}

其中

data.content 是核心,即推荐的诗句

data.matchTags 是与你相关的标签,也是推荐给你的部分理由。

data.recommendedReason 是推荐原因,暂未支持。

data.cacheAt 是指我们会对每个 Token 进行预生成推荐数据并缓存。正常情况下我们会10分钟更新一次缓存数据。

data.popularity 是我们对这句诗的流行度评价

data.origin 源诗信息

data.origin.translate 是整诗翻译,部分诗词有,部分没有

token 是当前用户的 token ,原则上,同一个用户,一段时间内 Token 应该不变。

ipAddress 是当前用户的 ip ,如果 IP 有异常,您需要查明您是否在服务端调用

错误返回:

{
    "status": "error",
    "errCode": 2001,
    "errMessage": "No matching handler"
}

errcode 是错误码,目前只有以下几种错误码,您也简单判断 HTTP 头中的状态码,对于错误返回,我们总不会返回 200

1001 :内部服务器错误,HTTP状态码 500

1002 :API路径不对,HTTP状态码 404

2002 :Token不是服务器签发,HTTP状态码 400

2003 :IP超过每日新用户限制,HTTP状态码 400,这很有可能是您没有正确保存 Cookies 或者 Token

6. JSON-TOKEN 接口

不支持 Cookies 环境的客户端必须调用本接口。

本接口的使用场景主要是:移动端、桌面端等不支持 Cookies 的地方调用。

小程序也调用本接口,但我们已经为您准备了 小程序快速安装 SDK

浏览器无法调用此接口,因为我们不会正确响应浏览器的 CORS 的预检请求(Preflighted requests)

您需要:

  1. 对于每一个用户第一次访问,先使用 获取 Token ,存到 Storage 里面。( Storage 表示一些长效的储存机制,您不应该存储到运行内存中)

  2. 之后每一次访问,把 TokenStorage 里面拿出来。

  3. 使用 附带 Token 的接口 , 发送附带 Token 的请求。

如果您仍然没有把握,可以查看我们的 小程序快速安装 的 SDK 的源码

6.1. 获取 Token

Token 用于鉴别和区分每个用户,获取后永久有效

如果您的调用频密,可能会过早用完推荐池(我们一般不会再推荐已推荐的诗词),导致推荐效果下降。您可以酌情在 3-30 天内为该用户重新获取一个 Token

获取 Token 的地址为,同样为 GET 方法

https://v2.jinrishici.com/token

返回的 Token 在 data 中:

{
	"status": "success",
	"data": "RgU1rBKtLym/MhhYIXs42WNoqLyZeXY3EkAcDNrcfKkzj8ILIsAP1Hx0NGhdOO1I"
}

6.2. 附带 Token 的接口

请求地址和标准 JSON 一致,也为 GET 方法:

https://v2.jinrishici.com/one.json

不同的是,您需要在 HTTP 的 Headers 头中指定 Token

X-User-Token: RgU1rBKtLym/MhhYIXs42WNoqLyZeXY3EkAcDNrcfKkzj8ILIsAP1Hx0NGhdOO1I

返回结果在此查看 返回结果

7. 服务端调用

原则上,为了获取到正确的 IP 定位信息,我们的接口都应该在终端直接调用,在实际用户处向我们发送请求。

但是,我们也保留一个不公开的后端调用接口,用于后端代理客户端发送请求,您可以向我们提供客户的真实 IP

如果您想用这个接口,请 联系我们

8. 接口测试

如何确保自己已经获取到了正确的 Token ,并且服务器已经识别到正确的IP?

你需要访问我们的调试接口,GET方法,如果是调试 JSON-TOKEN 接口 ,你同样可以发 Headers 给这个接口 :

https://v2.jinrishici.com/info

额外的 Headers (可选)

X-User-Token: 5894fcba-0f9b-435e-b460-bb02d19b8974

正常返回:

{
    "status": "success",
    "data": {
        "token": "5894fcba-0f9b-435e-b460-bb02d19b8974",
        "ip": "215.17.40.175",
        "region": "广东|深圳",
        "weatherData": {
            "temperature": 26,
            "windDirection": "东风",
            "windPower": 1,
            "humidity": 91,
            "updateTime": "23:10",
            "weather": "雨",
            "visibility": "33.43km",
            "rainfall": 0,
            "pm25": 23
        },
        "tags": [
            "桂花",
            "华南",
            "雨",
            "秋",
            "晚上"
        ],
        "beijingTime": "2018-09-17T23:47:48.194228"
    }
}

如果满足以下条件,则说明您的调用是正确的

  1. 对于同一用户,多次调用的 Token 是同一个

  2. IP是用户的IP,region识别正常

9. 使用协议

使用本API接口代表您 已经同意 以下的使用协议:

一、 使用本接口,您的网站、小程序、客户端、桌面端等终端(下简称终端)和您的行为必须满足以下条件:

  1. 终端内容和您的行为符合中国大陆法律

  2. 不恶意访问、攻击本接口

  3. 不使用自动化工具有目的地抓取保存本接口的数据

  4. 不伪造、仿冒、反向代理本接口

本网站已经在工信部备案,不想被查水表,请各位看官手下留情。 不要在违法网站上面调用本站接口啦。

 

二、 满足以下条件,您可以 免费使用 本接口

  1. 不以本接口及其提供的内容盈利 (以本接口及其提供的内容盈利的行为包括但不仅限于:出售本接口信息、在以本接口为主要内容的页面或应用中放置广告 等)

公司调用,商业调用,二次定制,商务合作,可以 联系我们

 

三、 本接口保留以下权利

  • 对同一 IP 的每日新用户数做出限制的权利。目前限制为 30新用户/日/IP

此限制主要为了打击以下行为,对于正常调用( 包括 网站快速安装小程序快速安装 )没有影响

  1. 标准 JSON 接口 不开启 withCredentials

  2. JSON-TOKEN 接口 不按规定保存并发送 Token

  3. 直接使用爬虫爬取 标准 JSON 接口图片形式调用

  • 对同一 IP 的短时间内密集访问做出限制的权利

目前暂未做出限制,后续根据服务器压力做出调整。承诺下限为 3次/秒/IP。
  • 对于 requests 等爬虫请求头做访问限制的权利

  • 对于违法网站的 Origin / Refer 拒绝响应的权利

  • 自行更改协议的权利。

 

四、免责声明

  1. 本接口提供的诗词数据来源于网络,如有侵权或错漏,请 联系我们

  2. 本接口推荐结果是根据时间、地点、天气等数据使用机器自动推荐,不代表本接口及其所有者赞成键入内容及推荐结果的内容或立场。

  3. 本接口为开放调用,不代表本接口及其所有者赞成调用本接口的终端上的内容或立场。

  4. 我们尽最大可能保证接口的稳定性,但对于本接口,特别是免费版本,我们不做任何稳定性、可靠性保证,由于本接口无法访问而带来的损失,本接口以及所有者不对此负责。

 

五、隐私权声明

  1. 本接口会临时获取用户公开的 IP 数据用以推荐,会向用户电脑置入 CookiesToken 信息记录历史推荐数据,如果您的终端用户认为此行为侵犯了他们的隐私,您应对此负责。

10. 常见问题

10.1. 项目是否开源?

本项目暂不开源,原因是推荐具有高度定制性,可重用性比较差,开源无益。

如果需要类似的返回一句话的接口,我已经在 Github 上开源了一个 旧API接口

10.2. 接口稳定吗?

我们尽最大可能维持接口的稳定性,长效性。

技术上,我们使用 Spring-Boot, Spring-WebFlux 开发,运行在 Netty 上,使用了 Mongo 数据库和 Redis 缓存,具有一定健壮性。

运维上,接口目前部署在腾讯云广州机房,具有一定的可靠性。

但对于恶意攻击和不可抗力因素导致的接口访问异常,我们只能尽快修复。

对于 标准 JSON 接口 调用的用户,您可以在接口失效的时候放置默认数据。对于 图片形式调用 调用的用户,您可以加置 alt 标签或者图片的描述性标签,用于无法访问时的备用显示。

使用后请尽量加 QQ群,方便我们向您通知一些情况。

10.3. 我们是如何推荐的?

  1. 根据调用的用户所在地,收集真实世界的信息,包括天气、时间、日期、事件等等

  2. 把真实世界信息转化为标签和其他特征,按特征拉取初步推荐池 推荐关联的标签有哪些?

  3. 判断诗词的好坏,并且根据一列算法对推荐池的诗词进行打分排序

  4. 去掉已经推荐过给该用户的诗词

  5. 在推荐池头部位置随机返回一条诗词

10.4. 推荐关联的标签有哪些?

注:该表仅供参考,和实际接口有出入。

标签
触发条件
气象触发标签
天气晴
天气雨
小雨
天气小雨/ 降水量
大雨
天气大雨/ 降水量
天气阴
天气多云
风力 >=2级
无风
风力 <= 1级
东风
东风,风力 >=2级
南风
南风,风力 >=2级
西风
西风,风力 >=2级
北风
北风,风力 >=2级
微风
风力 [2,3] 级
大风
风力 >= 4级
天气雪
雷电
雷电天气
干旱
沙尘
能见度
寒冷
气温 <= 10 度
炎热
气温 >= 30 度
时间触发标签
日出
当地日出时间后1小时
日落
当地日落前后1小时
正午
北京时间11-13点(人们通常认为12点为正午)
上午
[8-11]点
下午
[13-17]点
晚上
日落后1小时 - 晚上12点
凌晨
[0-5]点
日期触发标签
农历2-4月
农历5-7月
农历8-10月
农历10-1月
除夕
除夕
春节
春节
新年
元旦,春节
元宵
元宵
寒食
寒食
清明
清明
端午
端午
七夕
七夕
爱情
七夕, 元宵, 情人节,白色情人节
中秋
中秋
重阳
重阳
劳动
劳动节
爱国
国庆节,七七,九一八
妇女
妇女节
母亲
母亲节
父亲
父亲节
儿童
儿童节
老师
教师节
地理标签
华东
山东、江苏、安徽、浙江、福建、上海
华南
广东、广西、海南
华中
湖北、湖南、河南、江西
华北
北京、天津、河北、山西、内蒙古
西北
宁夏、新疆、青海、陕西、甘肃
西南
四川、云南、贵州、西藏、重庆
东北
辽宁、吉林、黑龙江
江南
上海、浙江、江苏
边塞
内蒙古,甘肃,宁夏,青海,青海
西域
新疆
徽州
安徽黄山
长安
陕西西安
武陵
湖南常德
浔阳
江西九江
姑苏
江苏苏州
苏州
江苏苏州
扬州
江苏扬州,江苏泰州,江苏南通,江苏盐城,江苏镇江,江苏南京,安徽天长,江苏淮安
燕京
北京
庐州
安徽合肥
琅琊
山东临沂
石头城
江苏南京
景德镇
江西景德镇
京口
江苏镇江
临安
浙江杭州
广陵
江苏扬州
武陵
湖南常德
钱塘
浙江杭州
金陵
江苏南京
幽州
北京
洛阳
洛阳
凉州
甘肃武威
齐州
山东济南
蜀地
四川
汝南
河南驻马店
大梁
河南开封
泰山
山东泰安
华山
陕西渭南
衡山
湖南衡阳
恒山
山西大同
嵩山
河南登封
黄山
安徽黄山
庐山
江西九江
雁荡山
浙江温州
河流
长江
四川攀枝花,四川宜宾,四川泸州,重庆,湖北宜昌,湖北荆州,湖北岳阳,湖北武汉,湖北鄂州,湖北黄石,江西九江,安徽安庆,安徽铜陵,安徽芜湖,安徽马鞍山,江苏南京,江苏镇江,江苏南通,上海
黄河
甘肃兰州,甘肃白银、宁夏石嘴山,内蒙古乌海,内蒙古巴彦淖尔, 内蒙古包头,陕西韩城,山西河津,山西永济、河南开封,河南三门峡,河南洛阳、山东滨州,山东济南
黄鹤楼
湖北武昌
滕王阁
江西南昌
岳阳楼
湖南岳阳
玉门
甘肃敦煌
阳关
甘肃敦煌
瓜州
江苏扬州
锦城
四川成都
成都
四川成都
洞庭
湖南岳阳
西湖
浙江杭州
赤壁
湖北咸宁
荒漠
荒漠地貌
草原
草原地貌
雪山
雪山地形
地震
混合标签
梅雨
华东地区,6月中-7月中,下雨
海棠
山东,陕西,湖北,江西,安徽,江苏,浙江,广东,广西;4-5月
桃花
华南、西南:2-4月
华中华东:3-4月
华北:4-5月
牡丹
全国;5月
丁香
西南,西北,华北,东北;4-5月
杏花
华中,华东,华北,东北,西南,西北 3 - 4月
梅花
全国 1-3月
杜鹃
华南,华中,华东;4-6月
荷花
全国;6-9月
桂花
华南,华中,华东 9-10 月
梨花
菊花
华北 4月
惩罚标签
白天(惩罚项)
日落-日出
夜晚(惩罚项)
日出-日落

11. 旧API接口

之前我们在 Github 上面开源了一款 一言·古诗词 API (Hitokoto API) 的源代码,同样是随机返回一条古诗词名句。

并且我们在 https://gushi.ci 上面继续运营,提供相关接口。

今日诗词API的定位是 gushi.ci API 的 升级版 ,提供效果更好的接口服务。

两个项目相比较:

今日诗词API最大的优势是智能推荐,以及更加完整的诗词内容输出,并且域名已经备案,可以在小程序内调用。

而 gushi.ci 的 API 则是随机返回,优势是响应速度更快,配置更加简单,可以只返回某一分类下的诗词,开放源代码。

我们当然推荐您使用 今日诗词 API,但 gushi.ci API 我们也会继续维护。

12. 支持我们

如果您想支持我们的接口持续发展,您可以在您调用的网站等终端添加我们的链接或者文字说明

<a href="https://www.jinrishici.com" target = "_blank">今日诗词 API</a>

或者,您可以帮我们多多推广宣传。

或者,您可以给我们提意见:联系我们 QQ群

十分感谢。

13. QQ群

QQ群:882330572

今日诗词官方群
300

欢迎加群,我们会在QQ群发布通知。

14. 更新历史

2018.10.31 更新今日诗词版本为 2.1 ,大幅降低推荐的重复性,可以显示更多没有看过的诗词

2018.10.25 更新浏览器 SDK 版本为 1.1,增强兼容性,支持 class 标签自动赋值

2018.9.23 今日诗词的第一个版本 2.0 BETA 上线,浏览器 SDK 1.0,小程序 SDK 1.0 上线

因为我们的 旧API接口 为1.X版本,所以 今日诗词API 版本号从 2.X 开始

15. 联系我们

请发送邮件联系: meetlhx#qq.com

欢迎反馈、商务联系

16. 关于我们

作者博客: 乱码

作者 Github: Github

17. 加入我们

欢迎熟悉推荐算法的攻城狮、前端、产品、UI、古诗词爱好者加入我们,共同改进这个产品,或者给我提意见也是可以哒!(当然目前暂时没有薪水😂)

18. 致谢

这个产品的诞生离不开彩云天气的 明理 师兄的建议,特此感谢。