Chinese Poem

Chinese Classical Poetry Database
Search Chinese classical poetry, including Tang poetry, Song poetry, and Song lyrics, with keyword and type filters.

Method: GET
Path: /v1/text/chinese-poem
Demo: https://api.gugudata.io/v1/text/chinese-poem/demo
OpenAPI: https://gugudata.io/assets/openapi/gugudata.openapi.3.1.json

Request Parameters:

• appkey (string, required): Application key used for request authentication. Supply the value as a query parameter, form field, or multipart field according to the request content type.
• keywords (string, optional): Keyword used for fuzzy matching against the searchable text fields supported by this endpoint.
• pagesize (integer, optional): Number of records returned per page.
• pagenumber (integer, optional): One-based page number for pagination.
• type (string, optional): Poetry type filter. Accepted values are 唐诗, 宋诗, and 宋词.
• searchtype (string, optional): Search scope accepted by the upstream contract. The demo uses all.

Response Fields:

• dataStatus (object, required): Response metadata. dataStatus.statusCode is a response body status field, not the HTTP status code.
• dataStatus.requestParameter (string, required): Normalized request parameters echoed by the service. Sensitive credentials are omitted when available.
• dataStatus.statusCode (integer, required): Response body status field. Successful demo responses currently return 100.
• dataStatus.statusDescription (string, required): Response body status message. Successful demo responses currently return a Chinese message.
• dataStatus.responseDateTime (string, required): Response timestamp returned by the current service contract.
• dataStatus.dataTotalCount (integer, required): Total number of records that match the request.
• data (array, required): Primary response payload returned by the endpoint.
• data[].title (string, required): Title of the poem or lyric
• data[].author (string, required): Author name
• data[].content (array, required): Array of strings containing the poem/lyric content, each element is one line
• data[].type (string, required): Poetry type returned by the upstream dataset, such as 唐诗, 宋诗, or 宋词.

HTTP Status Codes:

• 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 concurrency or retry after the limit window resets.
• 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.

Business Status Codes:

• 100 Normal return: Request successful, poetry data returned
• -1 Request failed: Request processing failed
• 501 Parameter error: Invalid parameters or parameter type mismatch
• 429 Request frequency limited: Recommended QPS <= 5 per IP. Excessive requests may trigger rate limiting
• 502 Request frequency limited: Same IP excessive requests or detected as malicious data scraping
• 503 APPKEY permission exceeded/order expired: Please check your APPKEY status in developer center
• 504 APPKEY error: Please verify the APPKEY is obtained from developer center
• 505 Request count exceeded: Check API request limit and remaining quota
• 900 Internal API error: Service availability (SLA) is 99.8674%. Contact support if this occurs

Key Features:

• Comprehensive database of nearly 400,000 Chinese classical poetry entries.
• Fuzzy keyword matching across title, author, and content.
• Filter by poetry type: Tang poems, Song poems, and Song lyrics.
• Flexible pagination support for large result sets.
• Continuously updated and maintained dataset.
• Full API support for HTTPS (TLS v1.0 / v1.1 / v1.2 / v1.3).
• Fully compatible with Apple ATS.
• Nationwide multi-node CDN deployment.
• Ultra-fast response, API interface load balancing built with multiple servers.
• Perfect for educational apps, cultural applications, and literature research.

Details:
https://gugudata.io/details/chinesepoem