A proper service around a famous open corpus
Chinese Poetry API turns the large chinese-poetry/chinese-poetry collection into something an application can query without loading and normalizing repository files itself. The v0.6.0 database contains 371,313 works, 13,577 authors, and 11 dynasties. Tang poetry, Song lyrics, Yuan songs, the Book of Songs, the Analects, and other material sit behind one Go server and an SQLite database.
The project is documented in Chinese, with no English README. That is understandable for a Chinese literature service, but it matters to international engineering teams. Endpoint names and code examples are easy to follow, while operational explanations, issue reports, and release notes require Chinese reading or translation. The API content itself is Chinese by design.
The value is straightforward. You can list poems, authors, dynasties, and forms; fetch individual records; search by title, content, or author; or request a random poem. Both simplified and traditional Chinese are stored in the same database and selected with a lang parameter. Applications do not have to perform conversion on every response.
REST and GraphQL cover the useful paths
The REST surface uses conventional /api/v1 routes and page controls. List and random endpoints share filters for author, dynasty, type, and even a required character, which is handy for poetry games such as Feihualing. Unknown query parameters produce a 400 response instead of being silently ignored, and page size is capped at 100. Those small decisions make client mistakes visible.
GraphQL exposes poems, search, authors, and aggregate statistics through a single endpoint. The default configuration keeps schema introspection enabled but disables the browser playground in release mode. A complexity limit and separate request limits provide basic protection. REST users get direct curl examples, while GraphQL users get a few representative queries rather than a complete schema reference. You may need introspection or source reading for less obvious relationships.
Search is useful but not fully composable. The documented modes cover all fields, title, content, and author. An open issue points out that keyword search cannot also filter by dynasty, forcing a client to filter later. The maintainer said they intended to implement the request when time allowed, but it remains open. Do not describe that as shipped or schedule a dependent feature around it.
Docker makes the first run pleasantly small
The recommended command starts the published image on port 1279. On first launch, its startup script downloads the compressed poetry database, so the container does not need a manual data preparation step. Docker Compose adds a named volume, restart policy, and environment file. The image supports amd64 and arm64, includes a health check, and uses a compact Alpine runtime.
That convenience comes with two practical wrinkles. First, deployment depends on downloading a release database. Keep the volume persistent, verify the published checksum if you handle the asset yourself, and avoid letting an unpinned latest image change unexpectedly. Second, the Compose example publishes the port on the host. The service documents no users, API keys, or TLS. Its defenses are IP-based rate limits, with defaults of 10 requests per second and a burst of 20. Put authentication, HTTPS, request logging, and stricter abuse controls in a reverse proxy when the API is not private.
Source builds demand more than the Docker quick start. The repository uses a Git submodule for the corpus, so clones need --recurse-submodules or a separate initialization command. The build uses CGO and SQLite FTS5, while make process-data prepares source data. None of this is unusual, but Docker is clearly the lower-risk route for consumers who do not plan to change ingestion.
Corpus size is not the same as editorial quality
The database is the project's biggest asset and its biggest caveat. It inherits material from the upstream Chinese Poetry dataset, then builds simplified and traditional tables for serving. A large collection is valuable for discovery and experimentation, but it should not be treated as a scholarly critical edition.
An open issue reports multiple wrong characters in search results. The maintainer replied that this is a poetry-quality problem and directed corrections toward a related data repository, with updates intended to flow back upstream. That response is honest, but it leaves consumers responsible for validation. A classroom app, citation tool, or published anthology should compare selected works against an authoritative edition. A random-poem widget has a much lower risk threshold.
Traditional conversion also deserves sampling. Automated conversion is convenient, yet names, historical variants, and literary wording can require context. The README claims very fast conversion, but because v0.6.0 stores both variants, normal API consumers should care more about textual correctness than nanoseconds.
Healthy development, modest support depth
The last push was August 3, 2026, about a month after the v0.6.0 release on July 4. The eight open GitHub items split into three issues and five pull requests. Recent pull requests cover dependency maintenance and cursor pagination, while the maintainer responded directly to the two substantive API and data reports. This is healthy activity for a focused project, though it is not a large support organization.
Documentation gives a strong quick tour but stops early. The README covers Docker, source commands, REST calls, GraphQL examples, search modes, language selection, and corpus composition. It does not document production topology, authentication, backups, error response shapes, schema evolution, or an English path. The config file is readable and exposes connection pools, rate limits, GraphQL controls, and search limits, which partly fills the gap.
Chinese Poetry API is the right starting point when you need a self-hosted Chinese poetry service today and can accept responsibility for text verification. It removes considerable ingestion and API work without becoming a large platform. Keep it behind a gateway, pin the deployment, and curate any poems that reach educational or published output.