The service exposes 371,313 poems through REST and GraphQL
Chinese Poetry API packages the chinese-poetry dataset behind a Go server. Release v0.6.0 reports 371,313 poems, 13,577 authors, and 11 dynasties in one database. REST endpoints cover poems, random selection, search, authors, dynasties, forms, statistics, and health. GraphQL offers overlapping queries with edges and total counts. Every endpoint can switch between simplified zh-Hans and traditional zh-Hant data.
The documentation is primarily Chinese, with no English README linked or present in the material we inspected. That matches the subject and likely audience, but it affects operations as much as usage. Configuration notes, command descriptions, release changes, and issue reports are also Chinese. An English-only team can infer much from code examples, yet it will miss nuance in validation rules, dataset reports, and maintenance discussion.
Full-text search depends on an SQLite build feature
Search can target all text, titles, poem content, or authors. The database keeps separate simplified and traditional tables and creates full-text indexes for them. That design avoids converting every response on demand, but it makes SQLite's FTS5 extension part of the server contract. The repository's Makefile sets CGO_ENABLED=1 and the sqlite_fts5 build tag for builds and tests.
The Dockerfile makes the same dependency explicit. Its build stage installs a compiler, musl development files, and SQLite development headers, then compiles a static Go binary with the FTS5 tag. If you replace that image with a generic go build, successful compilation alone does not prove search migrations will work. Start the server against a fresh data directory and exercise both language indexes before shipping a custom binary.
What happened when we ran it
Our sandbox installed 122 Go packages in 28 seconds. The build succeeded in 66 seconds. The checkout at commit 1a01896 contained 2,384 files, roughly 18,837 lines of source, and occupied 380 MB. It included 3 CI workflow files, a Dockerfile, a Compose file, and a tests directory.
Tests exited with code 1 after 57 seconds, with 1 passing and 1 failing group out of 2. TestGraphQLCountFields failed while migrating the simplified Chinese tables because SQLite could not create poems_fts_zh_hans. The reported error was no such module: fts5 and named the sqlite_fts5 build tag as the required support. The processor package passed in the same log.
The published container owns the database download and persistence
The shortest deployment maps port 1279 from the published image. On startup, its script downloads the compressed database, while Compose mounts a named volume at /app/data so the result survives container replacement. The image exposes a health check and defaults to rate limiting. Open and idle database connection limits can be overridden, though the Compose comments say defaults are chosen from CPU count.
That convenience adds a startup dependency on the release asset and enough storage for the corpus. Version v0.6.0 publishes a compressed unified database plus SHA256 checksums. Operators should pin the image rather than use latest, verify the downloaded asset, back up the named volume if local changes matter, and test restart behavior without network access. The 380 MB checkout from our run is another reason to distinguish source, release data, and runtime storage in capacity planning.
Query validation is stricter than search composition
The REST examples document pagination, repeated type filters, dynasty and author filters, and random selection constrained by an author, form, dynasty, or character. Unknown parameters return HTTP 400 instead of being ignored, and the shown page-size ceiling is 100. That is a useful default for clients because a misspelled filter cannot silently broaden a request.
Search has a narrower combination model. Open issue 65 asks for keyword search plus a dynasty or dynasty ID, explaining that clients currently filter those results themselves. If a teaching app needs “moon poems from the Tang dynasty,” verify whether the current endpoint can express the query before building the interface around it. GraphQL may offer a different shape, but the README's search example does not establish that combined filter.
Corpus size does not guarantee textual accuracy
The API inherits its material from the chinese-poetry project and adds classification and simplified-traditional storage. Open issue 51 reports multiple wrong characters in poems returned by keyword search and supplies an example image. One issue cannot quantify the error rate across 371,313 records, but it is enough to reject an assumption that database presence equals editorial verification.
For a reading toy or developer demo, occasional source errors may be acceptable. A classroom, quotation product, or scholarly tool needs a provenance and correction process. Keep upstream identifiers where possible, sample well-known works in both scripts, and give users a way to report mistakes. The GPL-3.0 server license and the upstream dataset's terms also deserve review before redistributing a modified database or service.
August maintenance is active, with 11 open items and pull requests
GitHub showed 2,695 stars, 11 combined issues and pull requests, and a last push on August 24, 2026. Release v0.6.0 was published on July 4. August issue activity included database connection help, an MCP request, and community applications built on the API. Those dates support active maintenance; the small combined queue is not proof that the data is error-free.
Chinese Poetry API is a focused choice when you need local REST or GraphQL access to a large Chinese corpus. The container already encodes the tricky FTS5 build requirement that broke our 57-second test run. Prefer that route, pin its version, validate representative text, and confirm your exact search combinations. If all you need is data for offline processing, the upstream corpus is simpler and avoids another service.