Guide · Open source
How to use chinese-poetry: clone the JSON dataset and start building
Updated · written with AI from the project's own documentation and checked against our catalogue data
chinese-poetry is an open-source collection of classical Chinese literature stored as JSON files, covering Tang poems, Song poems, Song lyrics (ci) and other classics. This guide is for developers, researchers and students who want machine-readable classical texts. By the end you will know how to get the repository, what the dataset contains, and where its limits are.
chinese-poetrychinese-poetry/chinese-poetry · ★ 54k · MIT Install options & downloads Quick start
- 1Check your fit. Confirm you need raw JSON data for a developer or research project, not a finished reading app.
- 2Clone the repository. Run git clone https://github.com/chinese-poetry/chinese-poetry.git in your terminal.
- 3Open a dataset folder. Pick a collection such as 全唐诗 or 宋词 and look at its JSON files.
- 4Inspect the structure. Open one file to see its fields, since the README does not document a schema.
- 5Load the JSON in your code. Read the files with your language's JSON library and build your feature on top.
- 6Verify important texts. Cross-check poems you will display or publish against a trusted edition.
What is chinese-poetry and who is it for?
The project is a database of classical Chinese poetry. Its README describes it as covering 5.5 万 Tang poems, 26 万 Song poems and 2.1 万 Song lyrics (ci), plus other classical collections. The stated goal is to help developers build poetry applications without collecting the texts themselves.
It is raw data rather than a reading app. The README says the data comes from the internet, and corrections are handled by the community, so it is not a source of verified scholarly editions.
- Good fit: developers building poetry apps, websites or learning tools
- Good fit: researchers or students who want machine-readable classical texts
- Good fit: text analysis or word-frequency experiments on classical Chinese
- Poor fit: readers who want a polished reading app
- Poor fit: users who need verified scholarly editions
- Poor fit: non-developers who want something to click and use right away
Install chinese-poetry by cloning the repository
The project is installed by cloning the repository. The README lists no prerequisites. Run the clone command below in a terminal, then move into the folder that was created.
git clone https://github.com/chinese-poetry/chinese-poetry.gitExplore the dataset folders
The data is grouped into collections, and each one is a folder in the repository. The README lists the following sets, which you can open to see their JSON files.
- Tang and Song poems (唐诗宋诗, the folder 全唐诗)
- Song lyrics (全宋词, the folder 宋词)
- Five Dynasties: Huajianji (五代·花间集) and Nantang two-lords lyrics (南唐二主词)
- The Analects (论语) and Book of Songs (诗经)
- Youmengying (幽梦影) and Four Books and Five Classics (四书五经)
- Primer texts (蒙学) and the Nalan Xingde collection (纳兰性德诗集)
- Complete Tang poems, imperial edition (御定全唐詩)
Use the JSON files in your project
The README states that the data is distributed in JSON format so developers can start projects quickly. Load the files from the folder you need with your language's JSON reader. The README does not document a file schema or API, so inspect a file first to confirm its structure before writing code that depends on it.
The README's showcase lists projects that used this data, such as an offline Tang poems Android app, a char-RNN poem generator built with PyTorch, and a poetry calendar. These are examples from the README, not a guarantee of what you will build.
Check the data before you rely on it
The README says the data comes from the internet and that corrections are community-driven. Some controversial data needs community voting before it is added. For any work where accuracy matters, compare key poems against a source you trust.
The README also notes that the poem collection was gathered from a target site with limits, so collection was sometimes interrupted. Treat completeness as something to verify for your own use.
Licence and contributing
The project is licensed under MIT. The README invites pull requests and issues, and asks that corrections to poem lines include a source. Contribution guidelines are kept in the project wiki.
What people use it for
- Building an offline poetry app that reads Tang or Song poems from local files
- Running word-frequency analysis on Song lyrics or Tang poems
- Training a small char-RNN text-generation experiment, as in the README's showcase
- Creating a poetry calendar or website that displays classical lines
- Studying the Analects or Book of Songs in machine-readable form
Frequently asked questions
How do I install chinese-poetry?
Clone the repository with git clone https://github.com/chinese-poetry/chinese-poetry.git. The README lists no separate prerequisites or installer. After cloning, the JSON files are ready to read from the folders.
Is chinese-poetry free to use?
The project is licensed under MIT, as stated in the README and the LICENSE file in the repository. Check the LICENSE file for the full terms before using it in a product.
Does chinese-poetry have an app I can read in?
No. The README describes it as a database of JSON files for developers. Readers who want a polished reading experience will need a different tool, such as the comparable web projects listed in the README showcase.
Is the chinese-poetry data accurate?
The README says the data comes from the internet and that corrections are community-driven. For scholarly or published work, check important texts against a verified edition.
What alternatives are there to chinese-poetry?
Comparable projects mentioned include other forks of the Chinese Poetry Database and chinese-poetry-db-web, which the README lists as a MySQL-based web project built on this repository. Compare their formats and licences before choosing.
What data formats does chinese-poetry use?
The data is distributed as JSON files, according to the README. The README does not describe the exact schema, so open a file in the dataset folder to see its fields.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
chinese-poetry is a good choice for developers, researchers and students who need machine-readable classical Chinese texts under an MIT licence. If you want a ready-made reader, or you need verified scholarly editions, choose a curated edition or an existing reading app instead.
Install options & downloads