📦 Endpoints versioning
In order to avoid making breaking changes like this one in the future, API routes are now versionned. So the endpoint /api/species is now /api/v1/species. This let you the possibility to update when you're ready for the next releases.
📄 The data scructure changes
One of the biggest struggles we noticed was the pagination. Parsing the pagination links in the response headers was really painful, even if it's a stardard.
To solve this, we decided to include pagination links directly in the JSON response.
Now, all API calls wraps a data field, along with a links field, for pagination links, and optionally a meta fields, for high level informations such as counts.
🔧 Plant and species fields names changes
We removed and added a lot of fields. Most of USDA fields, such as propagation or products uses were removed, as they were too inaccurates.
You can get:
✂️ The filters and sort parameter changes
In order to avoid any name collision in parameters, filters are now scoped in the filter parameter. This means that common_name=mint is now filter[common_name]=mint.
You now also can exclude null values from results with the filter_not[ATTRIBUTE] parameter.
You can read more about filters in the documentation or see the The full list of filters in the reference.
📐 Ranges and orders
You can now query the range of values between two values with the range[FIELD]=min,max parameter.
For example, to query only species with a minimum height between 5 and 20 centimeters: api/v1/species?token=YOUR_TREFLE_TOKEN&range[maximum_height_cm]=5,20.
Filtering on ranges also allow to set only minimum or maximum values. For example:
/api/v1/species?range[maximum_height_cm]=5only return species higher than 5 cm/api/v1/species?range[maximum_height_cm]=,5only return species lower than 5 cm
You can read more about ranges in the documentation or see the The full list of ranges in the reference.
🖼 Better plants/species images
Images were fully reviewed, and are now splitted into categories: flower, leaf, habit, fruit, bark and other.
🌍 Species distributions
We began to collect plant locations (ex: France) and establishments (ex: Native) per zone, and they're now included in the /species/{species_slug} and /plants/{species_slug} endpoints.
You can also filter species by distribution zones or by establishment.
For example, to get plants native from Tibet: /api/v1/distributions/tibet/plants?filter[establishment]=native.
🔍 Blazing fast search engine
A new search endpoint for plants and species is available: /api/v1/species/search?q=term.
This search was designed to respond in milliseconds, and is ready for input autocomplete or "as you type" queries. You can see it in action on the landing page.
🧰 Error reporting and data collection
You can now report errors on species, or even submit corrections / changes to us, directly from an API call.
This means a lot to us, as we want our data to be everyone's, and believe strongly in the power of the community.
📕 Adoption of better standards
All units are following the International System of Units (SI), so we replaced feets by centimeters, inches by millimeters and so on.
Temperatures are in celcuis and kelvin degrees for now, as the conversion is more complex than for standard units.
Scientific names now follows the Binomial nomenclature. For the species, it 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.
Distribution zones for plants/species are following the World Geographical Scheme for Recording Plant Distributions (WGSRPD).
📦 JSON responses when listing plants and species are more complete
We added some fields in the response, such as an image url or the genus and family names, and embedded synonyms.
For example, when listing plants:
[
{
"id": 123486,
"slug": "corylus-avellana"
"scientific_name": "Corylus avellana",
"common_name": "common filbert",
"complete_data": false,
"link": "http://trefle.io/api/plants/123486",
}
]Is now
{
"data": [
{
"id": 123486,
"slug": "corylus-avellana",
"scientific_name": "Corylus avellana",
"common_name": "common filbert",
"author": "L.",
"bibliography": "Sp. Pl.: 998 (1753)",
"family": "Betulaceae",
"family_common_name": "Birch family",
"genus": "Corylus",
"genus_id": 2057,
"image_url": "https://bs.floristic.org/image/o/0d92cadb0d66dce1b0a8b26913125d6501e31d68",
"rank": "species",
"status": "accepted",
"synonyms": [
"Corylus sylvestris"
],
"year": 1753,
"links": {
"genus": "/api/v1/genus/corylus",
"plant": "/api/v1/plants/corylus-avellana",
"self": "/api/v1/species/corylus-avellana"
}
}
],
"links": {
"first": "/api/v1/plants?filter%5Bscientific_name%5D=Corylus+avellana&page=1",
"last": "/api/v1/plants?filter%5Bscientific_name%5D=Corylus+avellana&page=1",
"self": "/api/v1/plants?filter%5Bscientific_name%5D=Corylus+avellana"
},
"meta": {
"total": 1
}
}📋 Synonyms separation
Synonyms are no longer returned in the species or plants response, and are now included as an array in the response.
📐 Species fields scales changes
"Scale-like" fields, such as "light" or "soil adaptation" are no longer with values like 'Low', 'Medium' and 'High', but are now on a scale from 0 to 10.
📋 Common names split
Common names have been reviewed, and are now grouped by language.