Plants fields
When you query a species (or a plant), you will have a lot of fields to dig into. This is a simplified version of the reference that tries to explain a bit what each fields represents.
In doubt, refer to the reference
This documentation is way lighter than the reference, and do not show all the fields. If you have any doubt, please check the reference.
List responses only carry a subset of the fields
Collection endpoints (/api/v1/plants, /api/v1/species, their /search
variants, and nested lists such as /api/v1/genus/:id/plants) return a light
version of each record, so a page of results stays small. The two lists don't
carry exactly the same subset:
- Species lists:
id,common_name,slug,scientific_name,year,bibliography,author,status,rank,family,family_common_name,genus,genus_id,image_url,synonyms,links - Plants lists:
id,common_name,slug,scientific_name,year,bibliography,author,family_common_name,genus_id,main_species_id,vegetable,observations,image_url,links
Every other field (edible, edible_part, duration, common_names,
distribution, growth, specifications, images, sources…) is only
present on the detail endpoints, one record at a time:
# a list: light payload, no `edible` field
curl -g 'https://trefle.io/api/v1/species?token=YOUR_TREFLE_TOKEN&filter[edible]=true'
# one record: full payload, `edible` included
curl 'https://trefle.io/api/v1/species/fragaria-chiloensis?token=YOUR_TREFLE_TOKEN'
You can still filter and sort on the missing fields
Filtering, ordering and ranges are applied in the database, not on the
serialized response. filter[edible]=true works on a species list even though
edible is not part of that list's payload. Follow the record's links.self
to read the value back. Each endpoint validates its own filter keys (an unknown
key returns a 400 listing the valid ones), so a filter accepted by /species
is not necessarily accepted by /plants.
Species
| field | description |
|---|---|
| id (integer) | An unique identifier |
| common_name (string) | The usual common name, in english, of the species (if any). |
| slug (string) | An unique human-readable identifier (if you can, prefer to use this over id) |
| scientific_name (string) | The scientific name follows the Binomial nomenclature, and represents its genus and its species within the genus, resulting in a single worldwide name for each organism. The scientific name of an infraspecific taxons (ranks below species, such as subspecies, forms, varieties...) is a combination of the name of a species and an infraspecific epithet. A connecting term is used to denote the rank. See IAPT recommendation |
| year (integer) | The first publication year of a valid name of this species. See author citation |
| bibliography (string) | The first publication of a valid name of this species. See author citation |
| author (string) | The author(s) of the first publication of a valid name of this species. See author citation |
| status (string) | The acceptance status of this species by IPNI Can be: accepted and unknown. |
| rank (string) | The taxonomic rank of the species Can be: species, ssp, var, form, hybrid, and subvar. |
| family_common_name (string) | The common name (in english) of the species family |
| family (string) | The scientific name of the species family |
| genus_id (integer) | The id of the species genus |
| genus (string) | The scientific name of the species genus |
| image_url (string) | A main image url of the species |
| duration (array of strings) | The plant duration(s), which can be: - Annual: plants that live, reproduce, and die in one growing season. - Biennial: plants that need two growing seasons to complete their life cycle, normally completing vegetative growth the first year and flowering the second year. - Perennial: plants that live for more than two years, with the shoot system dying back to soil level each year. |
| edible_part (array of strings) | The plant edible part(s), if any. |
| edible (boolean) | Is the species edible? |
| vegetable (boolean) | Is the species a vegetable? |
| observations (string) | Some habit observations on the species |
| common_names (object) | Common names of the species per language |
| distribution (object) | (Deprecated) Distribution of the species per establishment |
| synonyms (array of objects) | The symonyms scientific names and authors |
| sources (array of objects) | The symonyms scientific names and authors |
| extras () |
links
API endpoints to related resources
| field | description |
|---|---|
| self (string) | API endpoint to the species itself |
| genus (string) | API endpoint to the species genus |
| plant (string) | API endpoint to the species plant |
images
| field | description |
|---|---|
| flower (array of objects) | Image(s) of the species flower |
| leaf (array of objects) | Image(s) of the species leaf |
| habit (array of objects) | Image(s) of the species habit |
| fruit (array of objects) | Image(s) of the species fruit |
| bark (array of objects) | Image(s) of the species bark |
| other (array of objects) | Image(s) of the species other |
distributions
Distribution of the species per establishment
| field | description |
|---|---|
| native (array of objects) | Zones the species is native from |
| introduced (array of objects) | Zones the species has been introduced |
| doubtful (array of objects) | Zones the species presence is doubtful |
| absent (array of objects) | Zones the species is absent and has been wrongly recorded |
| extinct (array of objects) | Zones the species is extinct |
flower
Flower related fields (the reproductive structure found in flowering plants)
| field | description |
|---|---|
| color (array of strings) | The flower color(s) |
| conspicuous (boolean) | Is the flower visible? |
foliage
Foliage (or leaves) related fields
| field | description |
|---|---|
| texture (string) | The general texture of the plant’s foliage Can be: fine, medium, and coarse. |
| color (array of strings) | The leaves color(s) |
| leaf_retention (boolean) | Does the leaves stay all year long? |
fruit_or_seed
Fruit or seed related fields
| field | description |
|---|---|
| conspicuous (boolean) | Is the fruit visible? |
| color (array of strings) | The fruit color(s) |
| shape (string) | Fruit shape |
| seed_persistence (boolean) | Are the fruit or seed generally recognized as being persistent on the plant? |
specifications
Species's main characteristics
| field | description |
|---|---|
| ligneous_type (string) | The ligneous type of the woody plant Can be: liana, subshrub, shrub, tree, and parasite. |
| growth_form (string) | The primary growth form on the landscape in relation to soil stabilization on slopes and streamsides? Each plant species is assigned the single growth form that most enhances its ability to stabilize soil |
| growth_habit (string) | The general appearance, growth form, or architecture of the plant |
| growth_rate (string) | The relative growth speed of the plant |
| average_height (object) | The average height of the species, in centimeters |
| maximum_height (object) | The maximum height of the species, in centimeters |
| nitrogen_fixation (string) | Capability to fix nitrogen in monoculture |
| shape_and_orientation (string) | The predominant shape of the species |
| toxicity (string) | Relative toxicity of the species for humans or animals Can be: none, low, medium, and high. |
growth
Growing of farming related fields
| field | description |
|---|---|
| days_to_harvest (number) | The average numbers of days required to from planting to harvest |
| description (string) | A description on how the plant usually grows |
| sowing (string) | A description on how to sow the plant |
| ph_maximum (number) | The maximum acceptable soil pH (of the top 30 centimeters of soil) for the plant |
| ph_minimum (number) | The minimum acceptable soil pH (of the top 30 centimeters of soil) for the plant |
| light (integer) | Amount of light in the species' habitats, on a scale from 0 (no light, <= 10 lux) to 10 (very intensive insolation, >= 100 000 lux). Ecological indicator |
| atmospheric_humidity (integer) | Relative humidity of the air in the species' habitats, on a scale from 0 (<=10%) to 10 (>= 90%). Ecological indicator |
| growth_months (array of strings) | The most active growth months of the species (usually all year round for perennial plants) |
| bloom_months (array of strings) | The months the species usually blooms |
| fruit_months (array of strings) | The months the species usually produces fruits |
| row_spacing (object) | The minimum spacing between each rows of plants, in centimeters |
| spread (object) | The average spreading of the plant, in centimeters |
| minimum_precipitation (object) | Minimum precipitation per year, in milimeters per year |
| maximum_precipitation (object) | Maximum precipitation per year, in milimeters per year |
| minimum_root_depth (object) | Minimum depth of soil required for the species, in centimeters. Plants that do not have roots such as rootless aquatic plants have 0 |
| minimum_temperature (object) | The minimum tolerable temperature for the species. In celsius or fahrenheit degrees |
| maximum_temperature (object) | The maximum tolerable temperature for the species. In celsius or fahrenheit degrees |
| soil_nutriments (integer) | Nutriment level of the soil in the species' habitats, on a scale from 0 (oligotrophic) to 10 (hypereutrophic). Ecological indicator |
| soil_salinity (integer) | Salinity of the soil in the species' habitats, on a scale from 0 (non-saline) to 10 (hyperhaline). Ecological indicator |
| soil_texture (integer) | Texture of the soil in the species' habitats, on a scale from 0 (clay) to 10 (rock) |
| soil_humidity (integer) | Humidity of the soil in the species' habitats, on a scale from 0 (xerophile) to 10 (subaquatic). Ecological indicator |
Ecological indicator values (light, humidity, soil)
The light, atmospheric_humidity, soil_humidity, soil_nutriments and soil_salinity fields are ecological indicator values, not measurements of what an individual plant tolerates. They come from the French Baseflor / Catminat database (Philippe Julve) and follow the Ellenberg-style convention: the number describes where the species is typically found in the wild along an environmental gradient, inferred from the habitats it occupies.
This matters when you compare Trefle to other sources:
- The USDA PLANTS database rates tolerance in agronomic classes (None / Low / Medium / High) defined by measurable thresholds — for salinity, the electrical conductivity of the soil solution. That is a different question, so the two can legitimately disagree. A coastal species such as Armeria maritima scores high as a habitat indicator while USDA rates its cultivated salt tolerance low.
- These indicators are calibrated for the temperate European flora. For species outside that range they are often absent, and when present should be treated with caution.
- A value of
0is meaningful (it places the species at the bottom of the gradient), it does not mean "unknown". Missing data isnull.
If you need to know where a specific value came from, the provenance endpoint tells you which source supplied it.
synonyms[]
| field | description |
|---|---|
| id (integer) | An unique identifier |
| name (string) | The scientific name of the symonym |
| author (string) | The author of the symonym |
sources[]
| field | description |
|---|---|
| id (string) | An unique identifier from the source |
| name (string) | The name of the source |
| citation (string) | How to cite the source |
| url (string) | The link on the source website, or the publication reference |
| last_update (string) | The last time the source was checked |