The database offers a read-only JSON API for programmatic access by research institutions. Access is whitelist-based: every client needs an API key and may call the API only from registered IP addresses or networks; endpoints serving controlled data additionally require the corresponding dataset scope. API keys and whitelists are configured by the data reviewers and system administrators.
To apply, sign in and submit a controlled-data application under Data Services, stating in the purpose that you need API access and giving the fixed IP address of the client; or contact us.
OpenAPI 3: https://ethnobotany.cn/openapi/v1.json
curl -H "X-Api-Key: ebk_XXXXXXXX_..." "https://ethnobotany.cn/api/v1/species?q=qiyeyizhihua"
| Status code | Meaning |
|---|---|
| 200 | Success |
| 401 | Missing or invalid API key, or the key is disabled or expired |
| 403 | The source IP is not whitelisted for this key, or the dataset scope required by the endpoint is missing |
| 404 | Record not found |
| 429 | Rate limit per minute exceeded (the Retry-After header gives the waiting time in seconds) |
Every response carries X-RateLimit-Limit and X-RateLimit-Remaining headers.
| Endpoint | Scope required | Description |
|---|---|---|
GET /api/v1/species?q=&page=&pageSize= | Open | Search species by Chinese name, pinyin, scientific name or synonym |
GET /api/v1/species/{guid} | Open | Species details: name reconciliation, synonyms and link counts |
GET /api/v1/species/{guid}/flora | Open | Flora treatment index (no full text) |
GET /api/v1/species/{guid}/papers | Open | Related papers |
GET /api/v1/species/{guid}/formulas | species_prescriptions | Historical formulas containing the species |
GET /api/v1/species/{guid}/uses | plant_uses | Plant use records (summary only) |
GET /api/v1/formulas?q=&dynasty= | prescriptions | Search formulas by name or pinyin |
GET /api/v1/formulas/{guid} | prescriptions | Formula details; ingredients/codes need prescription_composition, similar formulas need prescription_similarity |
GET /api/v1/papers?q= | Open | Search papers by title, DOI or PubMed ID |
GET /api/v1/names/match?name= | Open | Name matching: returns database species and accepted names |
GET /api/v1/stats | Open | Database statistics |
Paging: page starts at 1; pageSize defaults to 20 (maximum 100). Paged results have the form {page, pageSize, total, items}.
GET /api/v1/names/match?name=Panax%20pseudoginseng%20var.%20notoginseng
{
"canonicalName": "Panax pseudoginseng var. notoginseng",
"matchedVia": "scientific_name",
"results": [ { "chineseName": "三七", "acceptedName": "Panax notoginseng", "acceptedAuthor": "(Burkill) F.H.Chen",
"matchType": "synonym", "wcvpId": "146777", "ipniId": "91521-1", "wfoId": "wfo-0000263666", ... } ]
}
Data obtained through the API are subject to the Data Use Agreement and must cite the database. Data use agreement & ethics
Copyright © 2002-2025 Kunming Institute of Botany, Chinese Academy of Sciences. All rights reserved. [滇ICP备05000394号]
Address: 132 Lanhei Road, Kunming, Yunnan 650201, China Contact us