{
  "openapi": "3.1.1",
  "info": {
    "title": "Ethnobotany of China API",
    "description": "Read-only API of the Ethnobotany of China database (http://ethnobotany.cn). Every request needs an API key in the X-Api-Key header and must come from an IP address whitelisted for that key. Apply for a key via the Data Services page; keys and whitelists are managed by the data reviewers.",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://ethnobotany.cn/"
    }
  ],
  "paths": {
    "/api/v1/species": {
      "get": {
        "tags": [
          "ApiV1"
        ],
        "operationId": "species.search",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PagedResultOfSpeciesSummary"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/species/{guid}": {
      "get": {
        "tags": [
          "ApiV1"
        ],
        "operationId": "species.detail",
        "parameters": [
          {
            "name": "guid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpeciesDetail"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/species/{guid}/flora": {
      "get": {
        "tags": [
          "ApiV1"
        ],
        "operationId": "species.flora",
        "parameters": [
          {
            "name": "guid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/species/{guid}/papers": {
      "get": {
        "tags": [
          "ApiV1"
        ],
        "operationId": "species.papers",
        "parameters": [
          {
            "name": "guid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PaperSummary"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/species/{guid}/formulas": {
      "get": {
        "tags": [
          "ApiV1"
        ],
        "operationId": "species.formulas",
        "parameters": [
          {
            "name": "guid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PagedResultOfFormulaSummary"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/species/{guid}/uses": {
      "get": {
        "tags": [
          "ApiV1"
        ],
        "operationId": "species.uses",
        "parameters": [
          {
            "name": "guid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/formulas": {
      "get": {
        "tags": [
          "ApiV1"
        ],
        "operationId": "formulas.search",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dynasty",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PagedResultOfFormulaSummary"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/formulas/{guid}": {
      "get": {
        "tags": [
          "ApiV1"
        ],
        "operationId": "formulas.detail",
        "parameters": [
          {
            "name": "guid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormulaDetail"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/papers": {
      "get": {
        "tags": [
          "ApiV1"
        ],
        "operationId": "papers.search",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PagedResultOfPaperSummary"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/names/match": {
      "get": {
        "tags": [
          "ApiV1"
        ],
        "operationId": "names.match",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": { }
            }
          }
        }
      }
    },
    "/api/v1/stats": {
      "get": {
        "tags": [
          "ApiV1"
        ],
        "operationId": "stats",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteStats"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FormulaDetail": {
        "required": [
          "entryId",
          "guid",
          "name",
          "namePinyin",
          "composition",
          "efficacy",
          "indications",
          "dynasty",
          "year",
          "originalAuthor",
          "originalSource",
          "compilation",
          "ingredients",
          "codes",
          "similarEuclidean",
          "similarJaccard",
          "url"
        ],
        "type": "object",
        "properties": {
          "entryId": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "guid": {
            "type": "string"
          },
          "name": {
            "type": [
              "null",
              "string"
            ]
          },
          "namePinyin": {
            "type": [
              "null",
              "string"
            ]
          },
          "composition": {
            "type": [
              "null",
              "string"
            ]
          },
          "efficacy": {
            "type": [
              "null",
              "string"
            ]
          },
          "indications": {
            "type": [
              "null",
              "string"
            ]
          },
          "dynasty": {
            "type": [
              "null",
              "string"
            ]
          },
          "year": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "originalAuthor": {
            "type": [
              "null",
              "string"
            ]
          },
          "originalSource": {
            "type": [
              "null",
              "string"
            ]
          },
          "compilation": {
            "type": [
              "null",
              "string"
            ]
          },
          "ingredients": {
            "type": [
              "null",
              "array"
            ]
          },
          "codes": {
            "type": [
              "null",
              "array"
            ]
          },
          "similarEuclidean": {
            "type": [
              "null",
              "array"
            ]
          },
          "similarJaccard": {
            "type": [
              "null",
              "array"
            ]
          },
          "url": {
            "type": "string"
          }
        }
      },
      "FormulaSummary": {
        "required": [
          "entryId",
          "guid",
          "name",
          "namePinyin",
          "dynasty",
          "year",
          "originalSource",
          "url"
        ],
        "type": "object",
        "properties": {
          "entryId": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "guid": {
            "type": "string"
          },
          "name": {
            "type": [
              "null",
              "string"
            ]
          },
          "namePinyin": {
            "type": [
              "null",
              "string"
            ]
          },
          "dynasty": {
            "type": [
              "null",
              "string"
            ]
          },
          "year": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "null",
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "originalSource": {
            "type": [
              "null",
              "string"
            ]
          },
          "url": {
            "type": "string"
          }
        }
      },
      "NameMatchInfo": {
        "required": [
          "matchSource",
          "matchType",
          "score",
          "acceptedName",
          "acceptedAuthor",
          "acceptedFamily",
          "taxonStatus",
          "wcvpId",
          "ipniId",
          "wfoId",
          "chineseNameColChina",
          "checklistVersion"
        ],
        "type": "object",
        "properties": {
          "matchSource": {
            "type": "string"
          },
          "matchType": {
            "type": "string"
          },
          "score": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
            "type": [
              "null",
              "number",
              "string"
            ],
            "format": "double"
          },
          "acceptedName": {
            "type": [
              "null",
              "string"
            ]
          },
          "acceptedAuthor": {
            "type": [
              "null",
              "string"
            ]
          },
          "acceptedFamily": {
            "type": [
              "null",
              "string"
            ]
          },
          "taxonStatus": {
            "type": [
              "null",
              "string"
            ]
          },
          "wcvpId": {
            "type": [
              "null",
              "string"
            ]
          },
          "ipniId": {
            "type": [
              "null",
              "string"
            ]
          },
          "wfoId": {
            "type": [
              "null",
              "string"
            ]
          },
          "chineseNameColChina": {
            "type": [
              "null",
              "string"
            ]
          },
          "checklistVersion": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      },
      "PagedResultOfFormulaSummary": {
        "required": [
          "page",
          "pageSize",
          "total",
          "items"
        ],
        "type": "object",
        "properties": {
          "page": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "pageSize": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "total": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FormulaSummary"
            }
          }
        }
      },
      "PagedResultOfPaperSummary": {
        "required": [
          "page",
          "pageSize",
          "total",
          "items"
        ],
        "type": "object",
        "properties": {
          "page": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "pageSize": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "total": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaperSummary"
            }
          }
        }
      },
      "PagedResultOfSpeciesSummary": {
        "required": [
          "page",
          "pageSize",
          "total",
          "items"
        ],
        "type": "object",
        "properties": {
          "page": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "pageSize": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "total": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpeciesSummary"
            }
          }
        }
      },
      "PaperSummary": {
        "required": [
          "id",
          "title",
          "authors",
          "source",
          "year",
          "doi",
          "pubmedId",
          "url"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": [
              "null",
              "string"
            ]
          },
          "authors": {
            "type": [
              "null",
              "string"
            ]
          },
          "source": {
            "type": [
              "null",
              "string"
            ]
          },
          "year": {
            "type": [
              "null",
              "string"
            ]
          },
          "doi": {
            "type": [
              "null",
              "string"
            ]
          },
          "pubmedId": {
            "type": [
              "null",
              "string"
            ]
          },
          "url": {
            "type": "string"
          }
        }
      },
      "SiteStats": {
        "required": [
          "speciesWithChineseName",
          "plantTaxa",
          "reconciledChineseNamed",
          "floraTreatments",
          "formulas",
          "formulaIngredients",
          "formulaCodes",
          "speciesFormulaLinks",
          "useRecords",
          "economicFloraRecords",
          "himalayaRecords",
          "papers",
          "speciesPaperLinks",
          "synonyms",
          "folkKnowledge",
          "computedAt"
        ],
        "type": "object",
        "properties": {
          "speciesWithChineseName": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "plantTaxa": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "reconciledChineseNamed": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "floraTreatments": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "formulas": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "formulaIngredients": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "formulaCodes": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "speciesFormulaLinks": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "useRecords": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "economicFloraRecords": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "himalayaRecords": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "papers": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "speciesPaperLinks": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "synonyms": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "folkKnowledge": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "reconciledPct": {
            "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
            "type": [
              "number",
              "string"
            ],
            "format": "double"
          }
        }
      },
      "SpeciesDetail": {
        "required": [
          "entryId",
          "guid",
          "chineseName",
          "chineseNamePinyin",
          "scientificName",
          "author",
          "rank",
          "family",
          "familyChinese",
          "genus",
          "genusChinese",
          "nameMatch",
          "synonyms",
          "floraTreatments",
          "formulas",
          "useRecords",
          "papers",
          "url"
        ],
        "type": "object",
        "properties": {
          "entryId": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "guid": {
            "type": "string"
          },
          "chineseName": {
            "type": [
              "null",
              "string"
            ]
          },
          "chineseNamePinyin": {
            "type": [
              "null",
              "string"
            ]
          },
          "scientificName": {
            "type": [
              "null",
              "string"
            ]
          },
          "author": {
            "type": [
              "null",
              "string"
            ]
          },
          "rank": {
            "type": [
              "null",
              "string"
            ]
          },
          "family": {
            "type": [
              "null",
              "string"
            ]
          },
          "familyChinese": {
            "type": [
              "null",
              "string"
            ]
          },
          "genus": {
            "type": [
              "null",
              "string"
            ]
          },
          "genusChinese": {
            "type": [
              "null",
              "string"
            ]
          },
          "nameMatch": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/NameMatchInfo"
              }
            ]
          },
          "synonyms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "floraTreatments": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "formulas": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "useRecords": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "papers": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "url": {
            "type": "string"
          }
        }
      },
      "SpeciesSummary": {
        "required": [
          "entryId",
          "guid",
          "chineseName",
          "scientificName",
          "author",
          "family",
          "acceptedName",
          "url"
        ],
        "type": "object",
        "properties": {
          "entryId": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "type": [
              "integer",
              "string"
            ],
            "format": "int32"
          },
          "guid": {
            "type": "string"
          },
          "chineseName": {
            "type": [
              "null",
              "string"
            ]
          },
          "scientificName": {
            "type": [
              "null",
              "string"
            ]
          },
          "author": {
            "type": [
              "null",
              "string"
            ]
          },
          "family": {
            "type": [
              "null",
              "string"
            ]
          },
          "acceptedName": {
            "type": [
              "null",
              "string"
            ]
          },
          "url": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "ApiV1"
    }
  ]
}