### Trefle API Response Example

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/getting-started.md

Example of the JSON response structure when querying the Trefle API for a list of plants. Includes data, links for pagination, and metadata.

```json
{
    "data": [
        {
            "author": "Schltr.",
            "bibliography": "Repert. Spec. Nov. Regni Veg. 16: 358 (1920)",
            "common_name": null,
            "family": "Orchidaceae",
            "family_common_name": null,
            "genus": "Aa",
            "genus_id": 14887,
            "id": 834556,
            "links": {
                "genus": "/api/v1/genus/aa",
                "plant": "/api/v1/plants/aa-achalensis",
                "self": "/api/v1/species/aa-achalensis"
            },
            "plant_id": 423071,
            "rank": "species",
            "scientific_name": "Aa achalensis",
            "slug": "aa-achalensis",
            "status": "accepted",
            "synonyms": [],
            "year": 1920
        },
        {
            "author": "Rchb.f.",
            "bibliography": "Xenia Orchid. 1: 18 (1854)",
            "common_name": null,
            "family": "Orchidaceae",
            "family_common_name": null,
            "genus": "Aa",
            "genus_id": 14887,
            "id": 834557,
            "links": {
                "genus": "/api/v1/genus/aa",
                "plant": "/api/v1/plants/aa-argyrolepis",
                "self": "/api/v1/species/aa-argyrolepis"
            },
            "plant_id": 423072,
            "rank": "species",
            "scientific_name": "Aa argyrolepis",
            "slug": "aa-argyrolepis",
            "status": "accepted",
            "synonyms": [
                "Altensteinia argyrolepis"
            ],
            "year": 1854
        } 
    ],
    "links": {
        "first": "/api/v1/species?page=1",
        "last": "/api/v1/species?page=20865",
        "next": "/api/v1/species?page=2",
        "self": "/api/v1/species"
    },
    "meta": {
        "total": 417293
    }
}
```

--------------------------------

### Trefle API - List Plants (NodeJS with https)

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/getting-started.md

An alternative method to fetch plant data from the Trefle API using NodeJS's native 'https' module. This example handles data chunks and error events.

```javascript
const https = require('https');

https.get('https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN', (resp) => {
  let data = '';

  // A chunk of data has been recieved.
  resp.on('data', (chunk) => {
    data += chunk;
  });

  // The whole response has been received. Print out the result.
  resp.on('end', () => {
    console.log(JSON.parse(data));
  });

}).on("error", (err) => {
  console.log("Error: " + err.message);
});
```

--------------------------------

### Trefle API - List Plants (NodeJS with node-fetch)

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/getting-started.md

Make a request to the Trefle API to get a list of plants using NodeJS and the node-fetch library. This example demonstrates asynchronous fetching and JSON parsing.

```javascript
const fetch = require('node-fetch');

(async () => {
  const response = await fetch('https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN');
  const json = await response.json();
  console.log(json);
})();
```

--------------------------------

### Balsam Fir Taxonomic Example

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/getting-started.md

Provides a concrete example of the Trefle API's taxonomic structure using the Balsam Fir (Abies balsamea).

```text
Kingdom -> Plantae – (Plants)
Subkingdom -> Tracheobionta – (Vascular plants)
Division -> Coniferophyta – (Conifers)
Class -> Pinopsida
Order -> Pinales
Family -> Pinaceae – (Pine family)
Genus -> Abies
Plant -> Abies balsamea
Species -> Abies balsamea
```

--------------------------------

### Trefle API Taxonomic Hierarchy

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/getting-started.md

Illustrates the hierarchical classification of plants within the Trefle API, starting from Kingdom and progressing down to Species.

```text
Kingdom
  -> Subkingdom
    -> Division
      -> Division class
        -> Division order
          -> Family
            -> Genus
              -> Plant
                -> Species
```

--------------------------------

### Trefle API - List Plants (cURL)

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/getting-started.md

Retrieve a list of all plants from the Trefle API using a cURL command in your terminal. Ensure you replace YOUR_TREFLE_TOKEN with your actual token.

```bash
curl 'https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN'
```

--------------------------------

### Trefle API - List Plants (Browser)

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/getting-started.md

Access the Trefle API to list all plants directly from your web browser. Requires a Trefle access token.

```browser
https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN
```

--------------------------------

### Install Dependencies

Source: https://github.com/treflehq/documentation/blob/master/README.md

Installs the necessary project dependencies using Yarn. This is the first step before running any other commands.

```bash
yarn
```

--------------------------------

### Plant vs. Species Distinction

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/getting-started.md

Explains the addition of a 'Plant' level in the Trefle API for commodity reasons, representing the main species, and its relationship with other subspecies, varieties, and hybrids.

```text
For example, our [balsam fir](https://en.wikipedia.org/wiki/Abies_balsamea) have:

- One species (which is our "plant"): `Abies balsamea`
- One sub-species: `Abies balsamea ssp. lasiocarpa`
- Two varieties: `Abies balsamea var. phanerolepis` and `Abies balsamea var. balsamea`
```

--------------------------------

### Start Local Development Server

Source: https://github.com/treflehq/documentation/blob/master/README.md

Starts a local development server for Trefle documentation. Changes are reflected live without server restarts.

```bash
yarn start
```

--------------------------------

### Get All Plants

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves a list of all plants. This is a basic GET request to the /api/v1/plants endpoint.

```APIDOC
GET /api/v1/plants
```

--------------------------------

### Get All Countries / Zones

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves a list of all countries or geographical zones. This is a basic GET request to the /api/v1/distributions endpoint.

```APIDOC
GET /api/v1/distributions
```

--------------------------------

### Querying the Second Page of Plants

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/pagination.md

Demonstrates how to request the second page of plant data from the Treflehq API. This involves appending the `page=2` parameter to the API endpoint. The example shows usage in a browser, via cURL, and with Node.js.

```browser
https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN&page=2
```

```curl
curl 'https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN&page=2'
```

```node
const fetch = require('node-fetch');

(async () => {
  const response = await fetch('https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN&page=2');
  const json = await response.json();
  console.log(json);
})();
```

--------------------------------

### Get All Genus

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves a list of all genus entries. This API call requires no specific parameters.

```APIDOC
GET /api/v1/genus
```

--------------------------------

### Get All Species

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves a list of all species, including subspecies and varieties. This is a basic GET request to the /api/v1/species endpoint.

```APIDOC
GET /api/v1/species
```

--------------------------------

### Get Introduced Plants in Marion-Prince Edward

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves plants introduced to the Marion-Prince Edward region. Filters results by establishment status.

```APIDOC
GET /api/v1/distributions/marion-prince-edward/plants?filter[establishment]=introduced
```

--------------------------------

### Search Plants - Multiple Client Examples

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/searching.md

Demonstrates how to search for plants using the Trefle API from different client environments: a web browser, the cURL command-line tool, and a Node.js script.

```Browser
Open your browser and navigate to

https://trefle.io/api/v1/plants/search?token=YOUR_TREFLE_TOKEN&q=coconut
```

```cURL
curl 'https://trefle.io/api/v1/plants/search?token=YOUR_TREFLE_TOKEN&q=coconut'
```

```JavaScript
const fetch = require('node-fetch');

(async () => {
  const response = await fetch('https://trefle.io/api/v1/plants/search?token=YOUR_TREFLE_TOKEN&q=coconut');
  const json = await response.json();
  console.log(json);
})();
```

--------------------------------

### Get Native Plants from Tibet

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves plants that are native to Tibet. Filters results by establishment status.

```APIDOC
GET /api/v1/distributions/tibet/plants?filter[establishment]=native
```

--------------------------------

### Get Edible Plants

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves a list of plants that have an edible part specified. This filters out plants where 'edible_part' is null.

```APIDOC
GET /api/v1/plants?filter_not[edible_part]=null
```

--------------------------------

### Get Countries / Zones with Less Than 10 Species

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves countries or zones that have fewer than 10 species. Filters results using a range query on 'species_count'.

```APIDOC
GET /api/v1/distributions?range[species_count]=,10
```

--------------------------------

### Get Plants in Antarctica

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves plants located in Antarctica. This utilizes the distributions endpoint to filter by geographical zone.

```APIDOC
GET /api/v1/distributions/antarctica/plants
```

--------------------------------

### Multiple Sorting Criteria

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/sorting.md

Shows how to apply multiple sorting criteria to API results. This example sorts plants first by 'year' in ascending order, and then by 'scientific_name' in descending order.

```APIDOC
https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN&order[year]=asc&order[scientific_name]=desc
```

--------------------------------

### Trefle API Client-Side Token Response

Source: https://github.com/treflehq/documentation/blob/master/docs/advanced/client-side-apps.md

This is an example of the JSON response received after successfully claiming a client-side token from the Trefle API. It includes the generated token and its expiration date, which can then be used for client-side API requests.

```json
{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMDYsIm9yaWdpbiI6IllPVVItV0VCU0lURS1VUkwiLCJpcCI6IlRIRS1XRUJTSVRFLVVTRVItSVAiLCJleHAiOjE1OTQ2NDIxNDh9.Vd2d3UK7zdNWZLBOn8y50NcUKuF8xFZgh6p7EB4fhVw",
  "expiration": "07-13-2020 14:09"
}
```

--------------------------------

### Get Tallest Trees

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves a list of trees, ordered by their maximum height in descending order. It excludes plants without a specified maximum height.

```APIDOC
GET /api/v1/plants?filter[ligneous_type]=tree&filter_not[maximum_height_cm]=null&order[maximum_height_cm]=desc
```

--------------------------------

### Get Species by Height Range

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves species with a maximum height between 5cm and 20cm. Uses a range query parameter for filtering.

```APIDOC
GET /api/v1/species?range[maximum_height_cm]=5,20
```

--------------------------------

### Trefle API - Species Correction Endpoint

Source: https://github.com/treflehq/documentation/blob/master/docs/advanced/complete-data.md

This section details the API endpoint for submitting corrections to species data. It outlines the HTTP method, URL structure, required parameters, and provides an example of a successful JSON response.

```APIDOC
POST /api/v1/corrections/species/{species_id}?token=YOUR_TREFLE_TOKEN

Description:
Submits a correction for a specific species record.

Request Body (JSON):
{
  "notes": "string", // Optional: Additional notes about the correction.
  "source_type": "external" | "user_observation" | "publication", // Type of the source.
  "source_reference": "string", // URL or identifier for the source.
  "correction": {
    // Fields to be corrected. Example:
    "maximum_height_value": "number",
    "maximum_height_unit": "string"
    // ... other fields can be corrected
  }
}

Example Request Body:
{
  "notes": "This tree can grows up to 68 meters",
  "source_type": "external",
  "source_reference": "https://conifersociety.org/conifers/abies-alba/",
  "correction": {
    "maximum_height_value": 6800,
    "maximum_height_unit": "cm"
  }
}

Example Response (Success):
{
  "data": {
    "id": "number",
    "record_type": "string",
    "record_id": "number",
    "user_id": "number",
    "warning_type": "string" | null,
    "change_status": "pending" | "approved" | "rejected",
    "change_type": "update" | "create" | "delete",
    "accepted_by": "string" | null,
    "notes": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "correction": { ... }, // Details of the submitted correction
    "changes": { ... } // Specific changes made
  },
  "meta": {
    "last_modified": "datetime"
  }
}

Notes:
- The `correction` object can contain various fields related to species data. Refer to the API documentation for a full list of correctable fields.
- Fields like `distributions` or `synonyms` cannot be corrected yet.
- Multiple values for a field can be separated by `|`, e.g., `"bloom_months": "jan|feb|mar|apr"`.
- Setting `notes` to `TEST` will result in the correction being automatically rejected without review.
```

--------------------------------

### Species Distribution Filtering

Source: https://github.com/treflehq/documentation/blob/master/blog/2020-07-15-1-6-0.md

Species can now be filtered by distribution zones or establishment status. For example, to get plants native from Tibet.

```APIDOC
Example: Get plants native from Tibet
/api/v1/distributions/tibet/plants?filter[establishment]=native
```

--------------------------------

### Build Static Content

Source: https://github.com/treflehq/documentation/blob/master/README.md

Generates static content for the Trefle documentation into the 'build' directory, ready for deployment on any static hosting service.

```bash
yarn build
```

--------------------------------

### Planting and Environmental Properties

Source: https://github.com/treflehq/documentation/blob/master/docs/advanced/complete-data.md

This section details various properties related to plant cultivation and environmental conditions. It includes measurements for height, spacing, precipitation, soil characteristics, and temperature, along with their respective units and value types.

```APIDOC
average_height_value (number)
maximum_height_unit (string): Can be: `in`, `ft`, `cm`, and `m`.
maximum_height_value (number)
planting_row_spacing_unit (string): Can be: `in`, `ft`, `cm`, and `m`.
planting_row_spacing_value (number): The minimum spacing between each rows of plants
planting_spread_unit (string): Can be: `in`, `ft`, `cm`, and `m`.
planting_spread_value (number): The average spreading of the plant
planting_days_to_harvest (integer)
maximum_precipitation_unit (string): Can be: `in`, `ft`, `mm`, `cm`, and `m`.
maximum_precipitation_value (number)
minimum_precipitation_unit (string): Can be: `in`, `ft`, `mm`, `cm`, and `m`.
minimum_precipitation_value (number)
minimum_root_depth_unit (string): Can be: `in`, `ft`, `cm`, and `m`.
minimum_root_depth_value (number)
ph_maximum (number)
ph_minimum (number)
soil_nutriments (integer): Required quantity of nutriments in the soil, on a scale from 0 (oligotrophic) to 10 (hypereutrophic)
soil_salinity (integer): Tolerance to salinity, on a scale from 0 (untolerant) to 10 (hyperhaline)
minimum_temperature_deg_c (number): The minimum required temperature in celcius degrees
```

--------------------------------

### Treflehq API Documentation

Source: https://github.com/treflehq/documentation/blob/master/docs/advanced/plants-fields.md

This section details the structure of the Treflehq API response for species data. It includes information on sources, related links, image types, distribution zones, and specific attributes of flowers, foliage, and fruits/seeds.

```APIDOC
sources (array of objects):
  The synonyms scientific names and authors.

extras ():
  No specific fields documented.

links:
  API endpoints to related resources.
  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:
  Image categories for the species.
  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.
  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).
  color (array of strings): The flower color(s).
  conspicuous (boolean): Is the flower visible?

foliage:
  Foliage (or leaves) related fields.
  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.
  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?
```

--------------------------------

### Get Species by Oldest Discoveries

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves species ordered by their discovery year in ascending order (oldest first).

```APIDOC
GET /api/v1/species?order[year]=asc
```

--------------------------------

### Plant Growth Parameters

Source: https://github.com/treflehq/documentation/blob/master/docs/advanced/plants-fields.md

Defines the various parameters associated with the growth and cultivation of plants. This includes environmental factors, soil requirements, and temporal aspects of growth, blooming, and fruiting.

```APIDOC
PlantGrowth:
  days_to_harvest (number): The average number of days required from planting to harvest.
  description (string): A description of how the plant usually grows.
  sowing (string): A description of 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): Required amount of light, on a scale from 0 (no light, <= 10 lux) to 10 (very intensive insolation, >= 100,000 lux).
  atmospheric_humidity (integer): Required relative humidity in the air, on a scale from 0 (<=10%) to 10 (>= 90%).
  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 row of plants, in centimeters.
  spread (object): The average spreading of the plant, in centimeters.
  minimum_precipitation (object): Minimum precipitation per year, in millimeters per year.
  maximum_precipitation (object): Maximum precipitation per year, in millimeters 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): Required quantity of nutriments in the soil, on a scale from 0 (oligotrophic) to 10 (hypereutrophic).
  soil_salinity (integer): Tolerance to salinity, on a scale from 0 (untolerant) to 10 (hyperhaline).
  soil_texture (integer): Required texture of the soil, on a scale from 0 (clay) to 10 (rock).
  soil_humidity (integer): Required humidity of the soil, on a scale from 0 (xerophile) to 10 (subaquatic).
```

--------------------------------

### Get Species with Red Flowers

Source: https://github.com/treflehq/documentation/blob/master/docs/examples/snippets.md

Retrieves species that have red flowers. Filters results based on the flower color attribute.

```APIDOC
GET /api/v1/species?filter[flower_color]=red
```

--------------------------------

### Trefle API Available Fields

Source: https://github.com/treflehq/documentation/blob/master/docs/advanced/complete-data.md

This section details the fields available for querying plant data via the Trefle API. It includes the field name, its data type, and a description of the information it represents. Some fields have specific allowed values or formats.

```APIDOC
scientific_name (string):
  The scientific name of the plant species.

rank (string):
  The taxonomic rank of the plant. Allowed values: `species`, `ssp`, `var`, `form`, `hybrid`, `subvar`.

genus (string):
  The genus of the plant.

year (integer):
  The year associated with the scientific name or classification.

author (string):
  The author credited with the scientific name.

bibliography (string):
  Bibliographical information related to the plant's classification.

common_name (string):
  The common name(s) of the plant in English. Multiple names can be separated by '|'.

observations (string):
  General observations about the plant.

planting_description (string):
  A description of how the plant typically grows.

planting_sowing_description (string):
  A description of the sowing process for the plant.

duration (string):
  The life duration of the plant. Multiple values can be separated by '|'. Allowed values: `annual`, `biennial`, `perennial`.

flower_color (string):
  The color(s) of the plant's flowers. Multiple values can be separated by '|'. Allowed values: `white`, `red`, `brown`, `orange`, `yellow`, `lime`, `green`, `cyan`, `blue`, `purple`, `magenta`, `grey`, `black`.

flower_conspicuous (boolean):
  Indicates whether the plant's flowers are conspicuous.

foliage_color (string):
  The color(s) of the plant's foliage. Multiple values can be separated by '|'. Allowed values: `white`, `red`, `brown`, `orange`, `yellow`, `lime`, `green`, `cyan`, `blue`, `purple`, `magenta`, `grey`, `black`.

foliage_texture (string):
  The texture of the plant's foliage. Allowed values: `fine`, `medium`, `coarse`.

leaf_retention (boolean):
  Indicates whether the plant retains its leaves.
```

--------------------------------

### Plant Database Schema Fields

Source: https://github.com/treflehq/documentation/blob/master/docs/advanced/complete-data.md

Defines the various fields used in the plant database, including their data types, descriptions, and allowed values. This covers attributes like fruit color, blooming months, growth rate, and environmental requirements.

```APIDOC
fruit_color (string):
  The species fruit color(s). Several values can be separated with "|".
  Allowed values: `white`, `red`, `brown`, `orange`, `yellow`, `lime`, `green`, `cyan`, `blue`, `purple`, `magenta`, `grey`, and `black`.

fruit_conspicuous (boolean):
  Indicates if the fruit is conspicuous.

fruit_seed_persistence (boolean):
  Indicates if the fruit seed has persistence.

fruit_months (string):
  The months when his species have fruits. Several values can be separated by "|".
  Allowed values: `jan`, `feb`, `mar`, `apr`, `may`, `jun`, `jul`, `aug`, `sep`, `oct`, `nov`, and `dec`.

bloom_months (string):
  The months when this species blooms. Several values can be separated by "|".
  Allowed values: `jan`, `feb`, `mar`, `apr`, `may`, `jun`, `jul`, `aug`, `sep`, `oct`, `nov`, and `dec`.

ground_humidity (integer):
  Required humidity of the soil, on a scale from 0 (xerophile) to 10 (subaquatic).

growth_form (string):
  The growth form of the plant.

growth_habit (string):
  The growth habit of the plant.

growth_months (string):
  The months when this species grows. Several values can be separated by "|".
  Allowed values: `jan`, `feb`, `mar`, `apr`, `may`, `jun`, `jul`, `aug`, `sep`, `oct`, `nov`, and `dec`.

growth_rate (string):
  The growth rate of the plant.

edible_part (string):
  The edible part of the species (if any). Several values can be separated by "|".
  Allowed values: `roots`, `stem`, `leaves`, `flowers`, `fruits`, and `seeds`.

vegetable (boolean):
  Indicates if the plant is a vegetable.

light (integer):
  Required amount of light, on a scale from 0 (no light, <= 10 lux) to 10 (very intensive insolation, >= 100 000 lux).

atmospheric_humidity (integer):
  Required relative humidity in the air, on a scale from 0 (<=10%) to 10 (>= 90%).

adapted_to_coarse_textured_soils (string):
  Indicates adaptation to coarse-textured soils.

adapted_to_fine_textured_soils (string):
  Indicates adaptation to fine-textured soils.

adapted_to_medium_textured_soils (string):
  Indicates adaptation to medium-textured soils.

anaerobic_tolerance (string):
  Indicates anaerobic tolerance.

average_height_unit (string):
  Unit for average height. Allowed values: `in`, `ft`, `cm`, and `m`.
```

--------------------------------

### Soil and Plant Parameters

Source: https://github.com/treflehq/documentation/blob/master/docs/advanced/complete-data.md

Defines the acceptable values and types for soil texture, ligneous type, and toxicity levels within the Treflehq project. Soil texture is rated on a scale, while ligneous type and toxicity have predefined categorical values.

```APIDOC
maximum_temperature_deg_c (number):
  The maximum required temperature in celcius degrees.

soil_texture (string):
  Required texture of the soil, on a scale from 0 (clay) to 10 (rock).
  Allowed values: `argile`, `intermediaire`, `limon`, `sable_fin`, `sable_grossier`, `graviers`, `galets`, `blocs_fentes_des_parois`, and `dalle`.

ligneous_type (string):
  Classification of the plant's woody nature.
  Allowed values: `liana`, `subshrub`, `shrub`, `tree`, and `parasite`.

toxicity (string):
  Indicates the toxicity level of the plant.
  Allowed values: `none`, `low`, `medium`, and `high`.
```

--------------------------------

### API Endpoint Versioning

Source: https://github.com/treflehq/documentation/blob/master/blog/2020-07-15-1-6-0.md

API routes are now versioned to prevent breaking changes. For example, the endpoint `/api/species` has been updated to `/api/v1/species`.

```APIDOC
Old Endpoint: /api/species
New Endpoint: /api/v1/species
```

--------------------------------

### Search Plants by Query

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/searching.md

This API endpoint allows you to search for plants using a query string. It requires your Trefle API token and the search term 'q'. The response includes a list of matching plants with detailed information.

```APIDOC
Endpoint: GET /v1/plants/search

Description: Searches for plants based on a query parameter.

Parameters:
  - token (string, required): Your Trefle API token.
  - q (string, required): The search query for plants.

Example Request:
https://trefle.io/api/v1/plants/search?token=YOUR_TREFLE_TOKEN&q=coconut

Example Response (partial):
{
    "data": [
        {
            "author": "L.",
            "bibliography": "Sp. pl. 2:1188.  1753",
            "common_name": "coconut palm",
            "family": "Arecaceae",
            "family_common_name": "Palm family",
            "genus": "Cocos",
            "genus_id": 1916,
            "id": 122263,
            "image_url": "https://bs.floristic.org/image/o/3d907876dd89dcf4880c50fb0786191a1cb95589",
            "links": {
                "genus": "/api/v1/genus/cocos",
                "plant": "/api/v1/plants/cocos-nucifera",
                "self": "/api/v1/species/cocos-nucifera"
            },
            "rank": "species",
            "scientific_name": "Cocos nucifera",
            "slug": "cocos-nucifera",
            "status": "accepted",
            "synonyms": [
                "Calappa nucifera",
                "Cocos nana",
                "Cocos indica",
                "Palma cocos",
                "Cocos mamillaris",
                "Cocos nucifera var. synphyllica",
                "Diplothemium henryanum",
                "Cocos nucifera var. spicata"
            ],
            "year": 1753
        }
    ]
}
```

--------------------------------

### Species Resource Fields

Source: https://github.com/treflehq/documentation/blob/master/docs/advanced/plants-fields.md

Defines the fields available for the Species resource. Each field includes its data type and a detailed explanation of its purpose and any specific conventions or references.

```APIDOC
Species:
  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](https://en.wikipedia.org/wiki/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](https://www.iapt-taxon.org/nomen/pages/main/art_24.html).
  year (integer):
    The first publication year of a valid name of this species. [See author citation](https://en.wikipedia.org/wiki/Author_citation_(botany)).
  bibliography (string):
    The first publication of a valid name of this species. [See author citation](https://en.wikipedia.org/wiki/Author_citation_(botany)).
```

--------------------------------

### Paginated API Response Structure

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/pagination.md

Illustrates the structure of a paginated API response, including the 'data' array containing the items for the current page, and the 'links' object providing navigation URLs for the first, last, next, previous, and current pages.

```json
{
    "data": [
        {
            "author": "Schltr.",
            "bibliography": "Repert. Spec. Nov. Regni Veg. Beih. 8: 38 (1921)",
            "common_name": null,
            "family": "Orchidaceae",
            "family_common_name": null,
            "genus": "Aa",
            "genus_id": 14887,
            "id": 834623,
            "links": {
                "genus": "/api/v1/genus/aa",
                "plant": "/api/v1/plants/aa-riobambae",
                "self": "/api/v1/species/aa-riobambae"
            },
            "plant_id": 423099,
            "rank": "species",
            "scientific_name": "Aa riobambae",
            "slug": "aa-riobambae",
            "status": "accepted",
            "synonyms": [
                "Altensteinia riobambae"
            ],
            "year": 1921
        },
        {
            "author": "Ames",
            "bibliography": "Proc. Biol. Soc. Washington 35: 81 (1922)",
            "common_name": null,
            "family": "Orchidaceae",
            "family_common_name": null,
            "genus": "Aa",
            "genus_id": 14887,
            "id": 834625,
            "links": {
                "genus": "/api/v1/genus/aa",
                "plant": "/api/v1/plants/aa-rosei",
                "self": "/api/v1/species/aa-rosei"
            },
            "plant_id": 423100,
            "rank": "species",
            "scientific_name": "Aa rosei",
            "slug": "aa-rosei",
            "status": "accepted",
            "synonyms": [
                "Altensteinia rosei"
            ],
            "year": 1922
        } 
    ],
    "links": {
        "first": "/api/v1/species?page=1",
        "last": "/api/v1/species?page=20865",
        "next": "/api/v1/species?page=3",
        "prev": "/api/v1/species?page=1",
        "self": "/api/v1/species?page=2"
    },
    "meta": {
        "total": 417293
    }}
```

--------------------------------

### Filter Parameter Changes

Source: https://github.com/treflehq/documentation/blob/master/blog/2020-07-15-1-6-0.md

Filters are now scoped within the 'filter' parameter to avoid name collisions. For example, `common_name=mint` is now `filter[common_name]=mint`. Additionally, null values can be excluded using `filter_not[ATTRIBUTE]`.

```APIDOC
Old Filter: common_name=mint
New Filter: filter[common_name]=mint

Exclude Null Values: filter_not[ATTRIBUTE]=value
```

--------------------------------

### Sources Array Schema

Source: https://github.com/treflehq/documentation/blob/master/docs/advanced/plants-fields.md

Defines the structure and fields for each source object within the sources array. Each field specifies the data type and a brief description of its purpose.

```APIDOC
sources[]:
  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
```

--------------------------------

### Basic Sorting by Year (Ascending)

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/sorting.md

Demonstrates how to sort plants by their 'year' field in ascending order using the Trefle API. This is useful for chronological ordering.

```browser
https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN&order[year]=asc
```

```curl
curl 'https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN&order[year]=asc'
```

```javascript
const fetch = require('node-fetch');

(async () => {
  const response = await fetch('https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN&order[year]=asc');
  const json = await response.json();
  console.log(json);
})();
```

--------------------------------

### Filter Plants by Common Name

Source: https://github.com/treflehq/documentation/blob/master/docs/guides/filtering.md

This snippet demonstrates how to filter plant search results to find plants with a specific common name, such as 'beach strawberry'. It shows examples for making the request via a web browser, using cURL, and with Node.js.

```APIDOC
GET /api/v1/plants

Query Parameters:
  token: YOUR_TREFLE_TOKEN (string, required) - Your API token.
  filter[common_name]: (string, optional) - Filter by common name. Values can be comma-separated for multiple entries.
  range[FIELD]: (string, optional) - Filter by a range of values for a specific field. Format: 'min,max'.

Example Request:
https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN&filter[common_name]=beach%20strawberry

Example Response (JSON):
{
    "data": [
        {
            "author": "(L.) Mill.",
            "bibliography": "Gard. Dict. ed. 8 : n.° 4 (1768)",
            "common_name": "beach strawberry",
            "complete_data": true,
            "family_common_name": "Rose family",
            "genus_id": 2585,
            "id": 131974,
            "image_url": null,
            "links": {
                "genus": "/api/v1/genus/fragaria",
                "self": "/api/v1/plants/fragaria-chiloensis",
                "species": "/api/v1/plants/fragaria-chiloensis/species"
            },
            "main_species_id": 137607,
            "observations": "Bolivia, C. & S. Argentina",
            "scientific_name": "Fragaria chiloensis",
            "slug": "fragaria-chiloensis",
            "vegetable": false,
            "year": 1768
        }
    ],
    "links": {
        "first": "/api/v1/plants?filter%5Bcommon_name%5D=beach+strawberry&page=1",
        "last": "/api/v1/plants?filter%5Bcommon_name%5D=beach+strawberry&page=1",
        "self": "/api/v1/plants?filter%5Bcommon_name%5D=beach+strawberry"
    },
    "meta": {
        "total": 1
    }
}
```

```browser
https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN&filter[common_name]=beach%20strawberry
```

```curl
curl 'https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN&filter[common_name]=beach%20strawberry'
```

```node
const fetch = require('node-fetch');

(async () => {
  const response = await fetch('https://trefle.io/api/v1/plants?token=YOUR_TREFLE_TOKEN&filter[common_name]=beach%20strawberry');
  const json = await response.json();
  console.log(json);
})();
```