chinese-poetry-api README

The project's README from github.com/palemoky/chinese-poetry-api. As one markdown file: README.md.

chinese-poetry

中国古诗词 API 服务

Docker Image Docker Image Size pre-commit License

基于 Go 语言的高性能中国古诗词 API 服务，支持 REST 和 GraphQL 接口，提供简体/繁体中文、爬虫练习场等功能。

在线版：https://poetry.palemoky.com

palemoky%2Fchinese-poetry-api | Trendshift

特性

快速开始

使用 Docker（推荐）

docker run -d -p 1279:1279 palemoky/chinese-poetry-api:latest

完整配置参见 docker-compose.yml。

使用 Makefile

make help          # 查看所有可用命令
make build         # 构建项目
make process-data  # 处理数据
make run-server    # 启动服务

克隆仓库

本项目使用 Git Submodules 管理诗词数据，推荐使用以下命令快速克隆：

# 完整克隆（包含 submodules）
git clone --recurse-submodules --depth=1 https://github.com/palemoky/chinese-poetry-api.git

如果已经克隆了仓库，可以单独更新 submodules：

git submodule update --init --depth 1

API 使用

多语言支持

所有接口支持 lang 参数切换简繁体：

参数值 说明
zh-Hans 简体中文（默认）
zh-Hant 繁体中文

REST API

# 健康检查
curl "http://localhost:1279/api/v1/health"

# 统计信息
curl "http://localhost:1279/api/v1/stats"

# 简体中文（默认）
curl "http://localhost:1279/api/v1/poems"

# 繁体中文
curl "http://localhost:1279/api/v1/poems?lang=zh-Hant"

# 诗词列表（带过滤，与 /poems/random 使用同一组参数）
curl "http://localhost:1279/api/v1/poems?dynasty=唐"
curl "http://localhost:1279/api/v1/poems?author=李白&page=2&page_size=50"
curl "http://localhost:1279/api/v1/poems?dynasty_id=1&type_id=11&type_id=12" # 多个 type_id 为「或」关系

# 游标翻页：把上一页 pagination.next_cursor 的值回传给 after。
curl "http://localhost:1279/api/v1/poems?page_size=50&after=cG9lbTo0MjA"

# 搜索诗词
curl "http://localhost:1279/api/v1/poems/search?q=静夜思"

# 随机诗词
curl "http://localhost:1279/api/v1/poems/random"

# 随机诗词（带过滤）
curl "http://localhost:1279/api/v1/poems/random?author=李白"
curl "http://localhost:1279/api/v1/poems/random?type=五言绝句"
curl "http://localhost:1279/api/v1/poems/random?char=春" # 飞花令等单字场景
curl "http://localhost:1279/api/v1/poems/random?author=李白&type=五言绝句"
curl "http://localhost:1279/api/v1/poems/random?author=李白&type=五言绝句&dynasty=唐"
curl "http://localhost:1279/api/v1/poems/random?author=李白&dynasty=唐&type=五言绝句&type=七言绝句&type=五言律诗"

# 作者列表
curl "http://localhost:1279/api/v1/authors?page=1&page_size=20"

# 作者详情
curl "http://localhost:1279/api/v1/authors/1"

# 朝代列表
curl "http://localhost:1279/api/v1/dynasties"

# 朝代详情
curl "http://localhost:1279/api/v1/dynasties/1"

# 诗词体裁列表
curl "http://localhost:1279/api/v1/types"

# 诗词体裁详情
curl "http://localhost:1279/api/v1/types/10"

GraphQL API

端点：http://localhost:1279/graphql

# 繁体中文查询
query {
  poems(lang: ZH_HANT, pageSize: 10) {
    edges {
      node {
        title
        content
        author {
          name
        }
      }
    }
    totalCount
  }
}

# 搜索诗词
query {
  searchPoems(query: "静夜思", searchType: TITLE) {
    edges {
      node {
        title
        author {
          name
        }
      }
    }
  }
}

# 统计信息
query {
  statistics {
    totalPoems
    totalAuthors
    poemsByDynasty {
      dynasty {
        name
      }
      count
    }
  }
}

搜索功能

类型 说明 示例
all 全文搜索（默认） ?q=月
title 标题搜索 ?q=静夜思&type=title
content 内容搜索 ?q=床前明月光&type=content
author 作者搜索 ?q=李白&type=author

数据集

本项目基于 chinese-poetry 数据集，使用的是修正了错字、朝代与作者等问题的 palemoky/chinese-poetry（fix-typo 分支），包含：

分类 数量 分类 数量 分类 数量 分类 数量
五言绝句 16,860 七言绝句 82,744 五言律诗 59,681 七言律诗 68,696
乐府诗 6,714 五代词 543 宋词 21,347 元曲 10,904
诗经 305 楚辞 65 论语 20 四书五经 14
其他 76,077 
pie title 收录数据分布概览 (忽略极小值)
"七绝/七律" : 151440
"五绝/五律" : 76541
"宋词/五代词" : 21890
"元曲" : 10904
"乐府诗" : 6714
"其他" : 76077

致谢

chinese-poetry-api (palemoky/chinese-poetry-api)

full-text-search
Searching Database…

3.4K ·GitHub
Chinese-poetry-api
What is this?A high-performance API service for Chinese classical poetry written in Go, exposing both REST and GraphQL endpoints over a dataset of nearly 400,000 poems spanning Tang poetry, Song lyrics, Yuan qu and more.
Is this a library I embed, or a standalone server I deploy?It's a standalone server you deploy yourself (via Docker or a Go build), not a library you import into your own code.
How do I get it running?Clone the repo with Git submodules to pull in the poetry data, then run it with Docker Compose (recommended, config in docker-compose.yml) or build/run it via the included Makefile.
Do I need to fetch the poetry data separately?Yes, the actual poems live in a separate submodule repo (a fixed-typo fork of chinese-poetry), so you must clone with submodules or run a submodule update if you already cloned without them.
Is there anything limiting how much I can query it?Yes, it has built-in per-IP rate limiting specifically to prevent abuse of the public API.
Does the Docker image work on ARM servers, or only x86?The Docker image is multi-arch, supporting both amd64 and arm64.
How big is the poetry dataset?Roughly 400,000 entries, including 82,744 seven-character jueju, 68,696 seven-character lushi, 21,347 Song ci, 10,904 Yuan qu, plus the Book of Songs, Chu Ci and more.
What kinds of search does the API support?Full-text search by default (?q=月), plus dedicated title, content, and author search modes via the type parameter.
Can I get results in both Simplified and Traditional Chinese?Yes, every endpoint accepts a lang parameter (zh-Hans or zh-Hant) to switch between Simplified and Traditional Chinese, both stored in the same database.
How fast is the Simplified/Traditional conversion?The conversion is optimized for concurrency and runs at about 300ns per operation, using the gocc library.
What are similar projects?tyk, zincsearch, typesense, pansou, reaction, dgraph, cube, claude-relay-service
Which topics is it in?rate-limiting, full-text-search, arm64, chinese-language, graphql, dataset, search, i18n, docker-compose, rest-api, backend, gplv3
Creator
palemoky
Size
12.9 MB
Stars
3.4K
Updated
CommitOct 07Releasev0.6.0Jul 04
Age
10mo
Commits · 90 Days