# Chinese Classical Poetry Database
Search nearly 400,000 works of classical Chinese poetry.
## API Overview
- **HTTP Protocol:** HTTPS
- **HTTP Method:** GET
- **HTTP Endpoint:** https://api.gugudata.io/v1/text/chinese-poem
- **Response Type:** application/json; charset=utf-8
- **DEMO Endpoint:** https://api.gugudata.io/v1/text/chinese-poem/demo
- **Live Demo:** https://gugudata.io/demo/chinesepoem
- **Postman:** https://www.postman.com/gugudata/gugudata-io
- **LLM Page:** https://gugudata.io/details/chinesepoem/llm
- **Raw Markdown:** https://gugudata.io/details/chinesepoem/llm.md
## Remote MCP
- **MCP Endpoint:** https://mcp.gugudata.io/mcp
- **MCP Guide:** https://gugudata.io/mcp/
- **Authorization:** OAuth authorization opens in the browser; do not paste appkeys into MCP clients.
- **Tool Scope:** MCP clients receive GuGuData API tools available to the authorized account.
## Data & API Features
- Nearly 400,000 poetry records: Explore a large structured collection of Chinese classical poetry for products, research, and content discovery.
- Tang and Song collections: Search Tang poems, Song poems, and Song lyrics through one consistent interface.
- Title, author, and content search: Find works by matching keywords across the poem title, author name, or full text.
- Poetry type filters: Limit results to the literary collection that best fits the learning or research experience.
- Structured paginated results: Browse large result sets predictably with titles, authors, content, types, and result totals.
- Education and cultural applications: Power reading tools, language-learning products, classroom resources, and digital humanities projects.
## API Request Parameters
| Name | Type | Is Required | Default Value | Remark |
| --- | --- | --- | --- | --- |
| appkey | string | true | YOUR_APPKEY | API key used to authenticate the request. |
| keywords | string | false | | Keyword used for fuzzy matching against the searchable text fields supported by this endpoint. |
| pagesize | integer | false | 10 | Number of records returned per page. |
| pagenumber | integer | false | 1 | One-based page number for pagination. |
| type | string | false | | Poetry type filter. Accepted values are `唐诗`, `宋诗`, and `宋词`. |
| searchtype | string | false | all | Search scope accepted by the upstream contract. The demo uses `all`. |
## API Response Parameters
| Name | Type | Remark |
| --- | --- | --- |
| dataStatus | object | Legacy response metadata. `dataStatus.statusCode` is not the HTTP status code for this endpoint family. |
| dataStatus.requestParameter | string | Privacy-safe summary of the normalized request. |
| dataStatus.statusCode | integer | Application-level status code. |
| dataStatus.statusDescription | string | Human-readable application status message. |
| dataStatus.responseDateTime | string | Time at which the response was generated. |
| dataStatus.dataTotalCount | integer | Number of matching or returned records for this request. |
| data | array<string> | Primary response payload returned by the endpoint. |
| data[].title | string | Title of the poem or lyric. |
| data[].author | string | Author name. |
| data[].content | array<string> | Array of strings containing the poem/lyric content, each element is one line. |
| data[].type | string | Poetry type returned by the upstream dataset, such as `唐诗`, `宋诗`, or `宋词`. |
## API Response Status Codes
| Status Code | Explanation of Status Code | Remarks |
| --- | --- | --- |
| 200 | Request processed successfully. | Some endpoints expose a separate application-level status field in the response body, such as `dataStatus.statusCode`. |
| 400 | Invalid request parameters or request format. | Check required fields, data types, and request body format. |
| 401 | Missing or unknown application key. | Provide a valid `appkey` with the request. |
| 403 | The application key is recognized but access is not allowed. | The key may be expired, inactive, or not permitted for the requested API. |
| 429 | Request rate or trial usage limit exceeded. | Reduce request frequency and retry with backoff. If a trial allowance is exhausted, check Trial Keys for remaining requests and subscribe to continue. |
| 500 | Internal service error. | Retry later or contact support if the error persists. |
| 503 | Upstream service unavailable. | Retry later; the requested upstream dependency is temporarily unavailable. |
## cURL Example
```bash
curl --location 'https://api.gugudata.io/v1/text/chinese-poem?appkey=YOUR_APPKEY&keywords=YOUR_VALUE&pagesize=10&pagenumber=1&type=YOUR_VALUE&searchtype=all'
```