今日诗词 API

https://www.jinrishici.com/doc/
Admin
今日诗词 API is an intelligent poetry recommendation service that provides classical Chinese poetry...
Tokens:15,349
Snippets:76
Trust Score:8.7
Update:3 days ago
Show doc for...
Tokens:
Raw
### GET https://v2.jinrishici.com/one.json

Source: https://www.jinrishici.com/doc

浏览器直接访问接口，适用于浏览器插件和 IOS 捷径。该接口会返回一首推荐诗词及其相关信息，并自动发送一个等效于 Token 的 Cookies。注意此接口仅适用于浏览器直接访问，不适用于网站调用。

```APIDOC
## [GET] https://v2.jinrishici.com/one.json

### Description
浏览器直接访问接口，适用于浏览器插件和 IOS 捷径。该接口会返回一首推荐诗词及其相关信息，并自动发送一个等效于 Token 的 Cookies。注意此接口仅适用于浏览器直接访问，不适用于网站调用。

### Method
GET

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

### Response
#### Success Response (200)
- **status** (string) - 固定为 "success"
- **data** (object) - 包含推荐诗词的详细信息
  - **id** (string) - 诗词的唯一标识
  - **content** (string) - 推荐的诗句
  - **popularity** (number) - 诗句的流行度评价
  - **origin** (object) - 源诗信息
    - **title** (string) - 诗名
    - **dynasty** (string) - 朝代
    - **author** (string) - 作者
    - **content** (array) - 诗的全文
    - **translate** (array) - 整诗翻译（部分诗词有）
  - **matchTags** (array) - 与用户相关的标签
  - **recommendedReason** (string) - 推荐原因（暂未支持）
  - **cacheAt** (string) - 缓存时间
- **token** (string) - 当前用户的 token
- **ipAddress** (string) - 当前用户的 IP 地址

#### Response Example
{
    "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"
}

#### Error Response
- **status** (string) - 固定为 "error"
- **errCode** (number) - 错误码
- **errMessage** (string) - 错误信息

#### Error Codes
- **1001** - 内部服务器错误，HTTP状态码 500
- **1002** - API路径不对，HTTP状态码 404
- **2002** - Token不是服务器签发，HTTP状态码 400
- **2003** - IP超过每日新用户限制，HTTP状态码 400

#### Error Response Example
{
    "status": "error",
    "errCode": 2001,
    "errMessage": "No matching handler"
}
```

--------------------------------

### GET https://v2.jinrishici.com/sentence

Source: https://www.jinrishici.com/doc

获取诗词推荐。需要在 HTTP 请求头中指定 Token（X-User-Token），返回结果为 JSON 格式的诗词数据。

```APIDOC
## [GET] https://v2.jinrishici.com/sentence

### Description
获取诗词推荐。需要在 HTTP 请求头中指定 Token（X-User-Token），返回结果为 JSON 格式的诗词数据。

### Method
GET

### Endpoint
https://v2.jinrishici.com/sentence

### Parameters
#### Headers
- **X-User-Token** (string) - Required - 用户 Token，用于标识用户

### Response
#### Success Response (200)
返回结果格式详见接口返回结果格式文档。

#### Response Example
（未提供具体示例）
```

--------------------------------

### GET https://v2.jinrishici.com/info

Source: https://www.jinrishici.com/doc

高级测试接口，用于验证接口安装是否正确。可附带 Token 以获取用户相关信息，返回结果包含 Token、IP、地区、天气、标签等信息。

```APIDOC
## [GET] https://v2.jinrishici.com/info

### Description
高级测试接口，用于验证接口安装是否正确。可附带 Token 以获取用户相关信息，返回结果包含 Token、IP、地区、天气、标签等信息。

### Method
GET

### Endpoint
https://v2.jinrishici.com/info

### Parameters
#### Headers
- **X-User-Token** (string) - Optional - 用户 Token，用于标识用户

### Response
#### Success Response (200)
- **status** (string) - 请求状态，成功时为 "success"
- **data** (object) - 包含以下字段：
  - **token** (string) - 当前使用的 Token
  - **ip** (string) - 用户 IP 地址
  - **region** (string) - 用户所在地区
  - **weatherData** (object) - 天气数据，包含温度、风向、风力、湿度、更新时间、天气、能见度、降雨量、PM2.5
  - **tags** (array) - 诗词标签列表
  - **beijingTime** (string) - 北京时间

#### Response Example
{
    "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"
    }
}
```

--------------------------------

### GET https://v2.jinrishici.com/token

Source: https://www.jinrishici.com/doc

获取用于鉴别用户的 Token，Token 永久有效。调用后需将返回的 Token 存储在长效存储中（如 localStorage），后续请求需附带该 Token。

```APIDOC
## [GET] https://v2.jinrishici.com/token

### Description
获取用于鉴别用户的 Token，Token 永久有效。调用后需将返回的 Token 存储在长效存储中（如 localStorage），后续请求需附带该 Token。

### Method
GET

### Endpoint
https://v2.jinrishici.com/token

### Response
#### Success Response (200)
- **status** (string) - 请求状态，成功时为 "success"
- **data** (string) - 获取的 Token 值

#### Response Example
{
  "status": "success",
  "data": "RgU1rBKtLym/MhhYIXs42WNoqLyZeXY3EkAcDNrcfKkzj8ILIsAP1Hx0NGhdOO1I"
}
```

--------------------------------

### GET /one.svg

Source: https://www.jinrishici.com/doc

获取今日诗词图片，支持通过查询参数自定义字体大小、间距和颜色。该接口仅限在网站中调用，不推荐在 APP 中使用。

```APIDOC
## GET /one.svg

### Description
获取今日诗词图片，支持通过查询参数自定义字体大小、间距和颜色。该接口仅限在网站中调用，不推荐在 APP 中使用。

### Method
GET

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

### Parameters
#### Query Parameters
- **font-size** (integer) - Optional - 字体大小(px)，默认值 20，合法范围 [8,50]
- **spacing** (number) - Optional - 间距(px)，默认值 1.5，合法范围 [0,30]
- **color** (string) - Optional - 颜色，默认值 black，合法值为颜色英文单词

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

### Response
#### Success Response (200)
返回 SVG 图片。

#### Response Example
（图片内容）
```

--------------------------------

### NPM SDK：带错误处理的 load 调用

Source: https://www.jinrishici.com/doc

可传入第二个错误处理函数，处理加载错误时的情况。

```javascript
const jinrishici = require('jinrishici');
jinrishici.load(result => {
  console.log(result);
}, errData => {
  console.log(err);
});
```

--------------------------------

### NPM 安装今日诗词 SDK

Source: https://www.jinrishici.com/doc

通过 npm 安装 jinrishici 包，仅支持浏览器环境，不支持 Node 和服务器渲染。

```bash
npm -i jinrishici --save
```

--------------------------------

### 微信小程序 SDK：调用加载函数

Source: https://www.jinrishici.com/doc

在 onLoad 或其他位置调用 jinrishici.load，传入回调函数处理返回结果。

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

--------------------------------

### NPM SDK：引入并调用 load 函数

Source: https://www.jinrishici.com/doc

在页面启动函数中引入 SDK 并调用 load，传入处理结果的函数。

```javascript
const jinrishici = require('jinrishici');
jinrishici.load(result => {
  console.log(result);
});
```

--------------------------------

### 微信小程序 SDK：引用 SDK 文件

Source: https://www.jinrishici.com/doc

在需要调用 SDK 的 Page 的 JS 文件顶部引用，注意文件夹深度确保路径正确。

```javascript
const jinrishici = require('../../utils/jinrishici.js')
```

--------------------------------

### 微信小程序 SDK：添加 API 地址到白名单

Source: https://www.jinrishici.com/doc

在微信后台配置请求白名单，允许小程序访问今日诗词 API 地址。

```text
https://v2.jinrishici.com
```

--------------------------------

### 安卓 SDK：初始化方法

Source: https://www.jinrishici.com/doc

在调用接口前初始化 SharedPreference 存储，两种方式任选其一；控件形式调用可跳过。

```java
//以下两种初始化方式任选一种即可
JinrishiciFactory.init(getContext());
JinrishiciClient.getInstance().init(getContext());
```

--------------------------------

### JS-SDK 高级加载函数调用

Source: https://www.jinrishici.com/doc

使用 jinrishici.load 函数传入回调以获取诗词数据，适用于需要自定义处理逻辑的场景。请确保在调用前已引入 SDK 文件，且不要将标签 ID 设置为 jinrishici-sentence 以避免自动加载。

```html
<script src="https://sdk.jinrishici.com/v2/browser/jinrishici.js" charset="utf-8"></script>
<script type="text/javascript">
  jinrishici.load(function(result) {
    // 自己的处理逻辑
    console.log(result)
  });
</script>
```

--------------------------------

### 安卓 SDK：Gradle 安装依赖

Source: https://www.jinrishici.com/doc

通过 Gradle 添加 android-sdk 依赖，版本 1.5。

```groovy
implementation 'com.jinrishici:android-sdk:1.5'
```

--------------------------------

### 安卓 SDK：异步获取诗词

Source: https://www.jinrishici.com/doc

使用 JinrishiciCallback 异步获取诗词，在 done 中处理成功逻辑，在 error 中处理错误。

```java
JinrishiciClient client = JinrishiciClient.getInstance();
client.getOneSentenceBackground(new JinrishiciCallback() {
	@Override
	public void done(PoetySentence poetySentence) {
		//TODO do something
		//在这里进行你的逻辑处理
	}

	@Override
	public void error(JinrishiciRuntimeException e) {
		Log.w(TAG, "error: code = " + e.getCode() + " message = " + e.getMessage());
		//TODO do something else
	}
});
```

--------------------------------

### 安卓 SDK：同步获取诗词

Source: https://www.jinrishici.com/doc

同步方法，请求出错时抛出 JinrishiciRuntimeException，需自行捕获；与异步方法二选一。

```java
PoetySentence poetySentence = JinrishiciClient.getInstance().getOneSentence();
```

--------------------------------

### Markdown 格式调用

Source: https://www.jinrishici.com/doc

在 Markdown 文档中嵌入今日诗词图片。

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

--------------------------------

### 协议占位符

Source: https://www.jinrishici.com/doc

协议文档中的空行占位符。

```text
　
```

--------------------------------

### Vue 中使用 NPM SDK 的示例

Source: https://www.jinrishici.com/doc

在 Vue 的 mounted 钩子中调用 load 方法，展示加载诗词并设置到 data 的示例。

```javascript
methods: {
  loadSentence: function() {
    jinrishici.load(result => {
      this.msg = result.data.content
    }, err => {
      console.log("test");
    })
  }
},
mounted: function(){this.loadSentence()}
```

--------------------------------

### 安卓 SDK：Maven 安装依赖

Source: https://www.jinrishici.com/doc

通过 Maven 添加 android-sdk 依赖，版本 1.5。

```xml
<dependency>
	<groupId>com.jinrishici</groupId>
	<artifactId>android-sdk</artifactId>
	<version>1.5</version>
	<type>pom</type>
</dependency>
```

--------------------------------

### 添加今日诗词 API 友情链接

Source: https://www.jinrishici.com/doc

在您的网站中添加此 HTML 代码以支持今日诗词 API 的持续发展。

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

--------------------------------

### 安卓 SDK：自定义控件 JinrishiciTextView

Source: https://www.jinrishici.com/doc

将控件添加进布局，自动请求数据并展示，无需手动初始化；可像 TextView 一样设置属性。

```xml
<com.jinrishici.sdk.android.view.JinrishiciTextView
	android:id="@+id/jinrisiciTextView"
	android:layout_width="wrap_content"
	android:layout_height="wrap_content"
	android:textColor="@color/colorAccent"
	android:textSize="18sp" />
<!--你可以像使用TextView那样对JinrishiciTextView进行设置-->
<!--如示例代码中的textColor和textSize属性-->
```

--------------------------------

### 网站快速安装通用代码

Source: https://www.jinrishici.com/doc

在 HTML 中放置指定 ID 的 span 标签并引入 SDK，SDK 会自动将内容替换为诗词。

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

--------------------------------

### 正确返回JSON示例

Source: https://www.jinrishici.com/doc

接口正常返回的JSON格式，包含status、data、token和ipAddress字段。data.content为核心诗句，data.matchTags为相关标签，data.cacheAt为缓存时间（约10分钟更新），data.popularity为流行度，data.origin为源诗信息，data.origin.translate为整诗翻译（部分诗词有）。

```json
{
    "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"
}
```

--------------------------------

### 自定义图片参数调用

Source: https://www.jinrishici.com/doc

通过 URL 参数自定义字体大小、间距和颜色。

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

--------------------------------

### HTML 格式调用

Source: https://www.jinrishici.com/doc

在 HTML 页面中嵌入今日诗词图片。

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

--------------------------------

### 博客与论坛集成示例

Source: https://www.jinrishici.com/doc

在博客或论坛模板（如 footer.php）中集成快速安装代码的示例。请确保代码放置在 PHP 标签之外。

```html
<footer id="footer" role="contentinfo">

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

    &copy; <?php echo date('Y'); ?> <a href="<?php $this->options->siteUrl(); ?>"><?php $this->options->title(); ?></a>.
    <?php _e('由 <a href="http://www.typecho.org">Typecho</a> 强力驱动'); ?>.
</footer><!-- end #footer -->
```

--------------------------------

### 图片调用地址

Source: https://www.jinrishici.com/doc

直接访问的图片调用地址。

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

--------------------------------

### 居中显示 HTML 调用

Source: https://www.jinrishici.com/doc

使用内联样式使图片在 DIV 中居中且不溢出。

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

--------------------------------

### 高级版诗词展示示例

Source: https://www.jinrishici.com/doc

一个完整的高级使用示例，展示如何将诗词内容及作者、朝代等信息渲染到指定的 HTML 元素中。

```html
<script src="https://sdk.jinrishici.com/v2/browser/jinrishici.js" charset="utf-8"></script>
<div id="poem_sentence"></div>
<div id="poem_info"></div>
<script type="text/javascript">
  jinrishici.load(function(result) {
    var sentence = document.querySelector("#poem_sentence")
    var info = document.querySelector("#poem_info")
    sentence.innerHTML = result.data.content
    info.innerHTML = '【' + result.data.origin.dynasty + '】' + result.data.origin.author + '《' + result.data.origin.title + '》'
  });
</script>
```

--------------------------------

### 错误返回JSON示例

Source: https://www.jinrishici.com/doc

接口错误返回的JSON格式，包含status、errCode和errMessage字段。错误码包括1001（内部服务器错误，HTTP 500）、1002（API路径不对，HTTP 404）、2002（Token不是服务器签发，HTTP 400）、2003（IP超过每日新用户限制，HTTP 400）。

```json
{
    "status": "error",
    "errCode": 2001,
    "errMessage": "No matching handler"
}
```
Tokens:
Raw