Repolode
Submit
palemoky

palemoky/chinese-poetry-api

Go-based API service for classical Chinese poetry, offering REST and GraphQL endpoints over a corpus of nearly 400,000 poems in simplified and traditional Chinese.

View on GitHubWebsite
Stars
3,465
Forks
455
Open issues
8
Last commit
13 days ago

What is it?

chinese-poetry-api is a Go service that serves a database of Chinese classical poetry, covering Tang poems, Song lyrics, Yuan drama songs and more, with nearly 400,000 works. Poems can be listed, filtered by dynasty, author, or genre, searched by title, content, or author, and fetched at random, including with single-character filters for games like 飞花令.

The API is available over both REST and GraphQL. Every endpoint accepts a lang parameter to return simplified (zh-Hans) or traditional (zh-Hant) Chinese text, since both variants are stored in the same database. The service includes built-in per-IP rate limiting, cursor-based pagination, and a Docker image with amd64 and arm64 builds.

The data comes from the chinese-poetry dataset, with typo and attribution corrections from a fork maintained by the author. Data processing and server startup are driven by a Makefile.

Key features

  • 01Serves REST and GraphQL APIs for poems, authors, dynasties and genres.
  • 02Switches between simplified and traditional Chinese with a lang parameter.
  • 03Supports full-text search and title, content, or author search.
  • 04Offers random poem retrieval with filters, including single-character matching.
  • 05Includes per-IP rate limiting and cursor pagination.
  • 06Ships as a Docker image for amd64 and arm64.

Use cases

  • Adding classical poetry lookup or quotes to an app or website.
  • Building a 飞花令 or poetry quiz game using random and character-filtered queries.
  • Practicing web scraping against a realistic, self-hosted data source.
  • Querying Chinese poetry data in traditional or simplified script.

Quick start

  1. 1

    Run with Docker

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

    Clone the repository with submodules

    git clone --recurse-submodules --depth=1 https://github.com/palemoky/chinese-poetry-api.git
  3. 3

    Process the data and start the server with Makefile

    make process-data
  4. 4

    Start the server

    make run-server

Things to know

  • The poetry data is sourced from submodules, so you must clone with submodules or fetch them separately.
  • The Makefile workflow requires running a data processing step before the server starts.

Topics

#poetry#chinese#api#graphql#rest-api#golang#docker

FAQ

What is chinese-poetry-api?
Go-based API service for classical Chinese poetry, offering REST and GraphQL endpoints over a corpus of nearly 400,000 poems in simplified and traditional Chinese. chinese-poetry-api is a Go service that serves a database of Chinese classical poetry, covering Tang poems, Song lyrics, Yuan drama songs and more, with nearly 400,000 works. Poems can be listed, filtered by dynasty, author, or genre, searched by title, content, or author, and fetched at random, including with single-character filters for games like 飞花令.
Is chinese-poetry-api free to use? What license does it have?
chinese-poetry-api is open source under the GPL-3.0 license. Check the license terms before using it in commercial products.
Is chinese-poetry-api still maintained?
Actively maintained. The last commit to chinese-poetry-api was on Oct 7, 2026.
What can I use chinese-poetry-api for?
Adding classical poetry lookup or quotes to an app or website. Building a 飞花令 or poetry quiz game using random and character-filtered queries. Practicing web scraping against a realistic, self-hosted data source. Querying Chinese poetry data in traditional or simplified script.
How do I install chinese-poetry-api?
Run with Docker: docker run -d -p 1279:1279 palemoky/chinese-poetry-api:latest Clone the repository with submodules: git clone --recurse-submodules --depth=1 https://github.com/palemoky/chinese-poetry-api.git Process the data and start the server with Makefile: make process-data Start the server: make run-server
Where can I get chinese-poetry-api?
The source code and installation instructions are on GitHub: https://github.com/palemoky/chinese-poetry-api

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects