Essential for Time‑Travel: 400k Chinese Poems in a One‑Command API

When I imagined traveling back to ancient China, I realized I couldn’t recite even twenty poems. Browsing GitHub, I discovered the open‑source project Chinese‑Poetry‑API (GitHub repo palemoky/chinese-poetry-api), which bundles almost 400,000 poems into an HTTP API that can be run with one Docker command, free of registration.

Project Overview

The service, written in Go and released in December 2025, uses the chinese-poetry dataset (a popular 50k‑star repository). It exposes poem metadata—title, author, dynasty, genre—through a simple API. An online demo is available at poetry.palemoky.com for quick, key‑less testing.

Data Volume

Seven‑character quatrains: 85,032

Seven‑character regulated verses: 69,028

Five‑character regulated verses: 71,400

Five‑character quatrains: 18,895

Song lyrics: 21,369

Yuan drama: 10,905

Classic texts (e.g., Shijing , Chuci , Lunyu ): 380 pieces

In total the library contains nearly 400,000 poems from over 13,000 authors, each entry already classified, eliminating the need for manual data cleaning.

API Features

The service offers two groups of endpoints: search and random. Search supports full‑text, title, content, and author queries. For example:

curl "http://localhost:1279/api/v1/poems/search?q=梦游天姥吟留别"

Random endpoints accept filters such as author, dynasty, and genre:

# Random Li Bai five‑character quatrain
curl "http://localhost:1279/api/v1/poems/random?author=李白&type=五言绝句"

A lang parameter toggles between Simplified and Traditional Chinese using the gocc library (≈300 ns per conversion).

curl "http://localhost:1279/api/v1/poems?lang=zh-Hant"

Both REST and GraphQL interfaces are provided; the GraphQL endpoint ( /graphql) returns poem and author data in a single request.

Additional Endpoints

/api/v1/authors – paginated author list

/api/v1/dynasties – dynasty list

/api/v1/types – genre list

These make it easy to build browsing pages that filter by dynasty or author.

Rate Limiting

The service includes built‑in IP rate limiting (default 10 req/s, burst 20 req/s) configurable via a simple file, which is crucial when exposing the API publicly.

Quick Start

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

After starting, verify health with: curl "http://localhost:1279/api/v1/health" Fetch a random poem to see the output:

curl "http://localhost:1279/api/v1/poems/random"

The Docker image supports both amd64 and arm64, so it runs on x86 servers, Raspberry Pi, and Macs. A Docker‑Compose file is provided for persistent volume storage.

Use Cases

Daily‑sentence widgets: call the random endpoint once per day for a homepage quote.

Poetry games (e.g., “fly‑flower” challenges): use the char filter to generate game prompts.

Educational apps: combine dynasty, author, and genre filters with search for curriculum‑aligned reading.

Web‑scraping practice: the online demo offers a well‑structured target site.

AI training data: the structured corpus serves as a knowledge base for Chinese language models.

Author’s Opinion

The main limitation is that the data originates from the external chinese-poetry dataset; the project's value lies in turning that raw data into a ready‑to‑use service. It is licensed under GPL‑3.0, so any modifications must be open‑sourced, which may affect commercial adoption.

Nevertheless, the author considers the project worthwhile because it automates data collection, cleaning, classification, API implementation, language conversion, and Docker packaging—tasks that together would take days, now reduced to a single command.

https://github.com/palemoky/chinese-poetry-api