# Fruityvice

> Look up the nutrition and botany of 49 fruits: calories, fat, sugar, carbohydrate and protein per 100 grams, plus the family, genus and order each one belongs to. Get a single fruit by name, search the catalogue by botanical group and by a nutrition range at once, and propose a fruit of your own for the public catalogue. Fruityvice is free and keyless: no account, no API key, nothing to set up.

App · Food & Drink · 3 actions. Web page: https://docs.lodol.com/docs/integrations/fruityvice

## Actions

### Add a fruit

Propose a fruit for the public Fruityvice catalogue, which anyone may contribute to. Give the name, the family, genus and order, and the five nutrition figures per 100 grams. A Fruityvice admin reviews every proposal, so the fruit does not appear in any lookup until they approve it, and this step says so rather than reporting it as added. A fruit already in the catalogue is not sent again: the record that already exists comes back instead.

**Inputs**

- Fruit name (`name`, text, required): What the fruit is called. This is the name everyone reading Fruityvice will look it up by, so use the common English name on its own -- 'Mangosteen', not 'Fresh Mangosteen (Thailand)'. A fruit already in the catalogue is reported back with its existing record instead of being proposed again.
- Family (`family`, text, required): The botanical family the fruit belongs to. Pick one already in the catalogue so the fruit files alongside its relatives, or type a new one if none fits.
- Genus (`genus`, text, required): The genus the fruit belongs to. Pick one already in the catalogue, or type a new one if none fits.
- Order (`order`, text, required): The order the fruit belongs to. Pick one already in the catalogue, or type a new one if none fits.
- Calories (`calories`, number, required): Calories in 100 grams of the fruit. Every Fruityvice figure is per 100 grams, never per fruit, so a banana is 96 and not 105. From 0 to 1000.
- Fat (grams) (`fat`, number, required): Grams of fat in 100 grams of the fruit. Nearly every fruit is close to zero here; avocado and the nuts filed as fruits are the exceptions. From 0 to 100.
- Sugar (grams) (`sugar`, number, required): Grams of sugar in 100 grams of the fruit. Sugar is part of the carbohydrate figure, so it should never be the larger of the two. From 0 to 100.
- Carbohydrates (grams) (`carbohydrates`, number, required): Grams of carbohydrate in 100 grams of the fruit. This is the total, so it includes the sugar figure above. From 0 to 100.
- Protein (grams) (`protein`, number, required): Grams of protein in 100 grams of the fruit. Under 2 for almost everything in the catalogue. From 0 to 100.

**Outputs**

- `existing_fruit` (object): The record already in the catalogue, when that is why nothing was sent; empty otherwise
- `fruit` (object): The record that was proposed. Its catalogue number is 0 because Fruityvice assigns one only on approval
- `message` (text): What happened, in a sentence fit to show a person
- `name` (text): The fruit that was proposed
- `per_grams` (number): How much fruit every figure describes, which is always 100 grams
- `status` (text): 'submitted' when it was sent, 'already_in_catalogue' when Fruityvice already has that fruit, 'already_awaiting_review' when somebody has already proposed it
- `submitted` (true/false): True when Fruityvice took the proposal. It still waits for an admin to approve it before it appears in any lookup

**Example output**

```json
{
  "existing_fruit": null,
  "fruit": {
    "calories": 73,
    "carbohydrates": 17.91,
    "family": "Clusiaceae",
    "fat": 0.58,
    "genus": "Garcinia",
    "id": 0,
    "name": "Mangosteen",
    "order": "Malpighiales",
    "protein": 0.41,
    "sugar": 16.11
  },
  "message": "Mangosteen was sent to Fruityvice and is waiting for an admin to review it. It will not appear in lookups until they approve it.",
  "name": "Mangosteen",
  "per_grams": 100,
  "status": "submitted",
  "submitted": true
}
```

### Find fruits

Every fruit Fruityvice holds, or only the ones that match. Narrow by botanical group (any family, genus or order, picked from a list that says which it is and how many fruits it reaches) and by a range on one of the five nutrition figures, together or apart. Sort by name or by any figure and cap the result, so 'the five lowest-sugar fruits' is one step. Leave every field empty for the whole catalogue.

**Inputs**

- Family, genus or order (`group`, text): Narrow to one botanical group. The list holds every family, genus and order in the catalogue, each labelled with which of the three it is and how many fruits it reaches, so 'Rutaceae - family, 5 fruits' can be picked without knowing what a family is. A few names are two kinds of group at once (Cactaceae is a family and a genus); they appear once and match both, and the result says which. Leave it empty for every fruit.
- Nutrient (`nutrient`, text): Which figure to filter on. Fill in 'At least', 'At most' or both beside it: Fruityvice refuses a nutrition search with no range at all. Every figure is per 100 grams of fruit. Leave it empty to search without a nutrition filter. One of: `calories`, `fat` (Fat (grams)), `sugar` (Sugar (grams)), `carbohydrates` (Carbohydrates (grams)), `protein` (Protein (grams)).
- At least (`min_value`, number): The lowest figure to include, counted in. Leave it empty for no lower limit. Only used when a nutrient is chosen. At least 0.
- At most (`max_value`, number): The highest figure to include, counted in. Leave it empty for no upper limit. Only used when a nutrient is chosen. At least 0.
- Sort by (`sort_by`, text): What to order the results by. By name unless you say otherwise. Sorting by a figure is how to ask for the lowest-sugar or highest-protein fruits: order by it and set 'How many to return' to the number you want. A fruit with no figure for that nutrient comes last either way round, because 'not recorded' is not 'none'. One of: `name`, `calories`, `fat`, `sugar`, `carbohydrates`, `protein`. Default: `name`.
- Sort direction (`sort_order`, text): Which way round to sort. Lowest first, or A to Z for names, unless you say otherwise. One of: `ascending` (Lowest first, or A to Z), `descending` (Highest first, or Z to A). Default: `ascending`.
- How many to return (`limit`, number): How many fruits to return. Defaults to 50, which is more than the whole catalogue, so nothing is left out unless you ask for less. Set it to 5 alongside 'Sort by' to get the five lowest or highest of something. The result always reports how many matched, so a shortened list never reads as a complete one. From 1 to 200. Default: `50`.

**Outputs**

- `catalogue_count` (number): How many fruits Fruityvice holds in total
- `count` (number): How many are in this result
- `fruits` (list): The fruits that matched, in the order asked for
- `group` (text): The family, genus or order that was filtered on, as the catalogue spells it; empty when none was
- `group_matched_as` (list): Which of family, genus and order that name turned out to be. Two entries for a name that is both, such as Cactaceae
- `limit` (number): The limit that was applied
- `matched_count` (number): How many matched before the limit was applied
- `max_value` (number): The upper bound that was applied, empty when none
- `min_value` (number): The lower bound that was applied, empty when none
- `nutrient` (text): The nutrient that was filtered on, empty when none
- `per_grams` (number): How much fruit every figure describes, which is always 100 grams
- `sort_by` (text): What the result was sorted by
- `sort_order` (text): Which way round it was sorted
- `truncated` (true/false): True when more matched than the limit returned

**Example output**

```json
{
  "catalogue_count": 49,
  "count": 3,
  "fruits": [
    {
      "calories": 25,
      "carbohydrates": 8.4,
      "family": "Rutaceae",
      "fat": 0.1,
      "genus": "Citrus",
      "id": 44,
      "name": "Lime",
      "order": "Sapindales",
      "protein": 0.3,
      "sugar": 1.7
    },
    {
      "calories": 29,
      "carbohydrates": 9,
      "family": "Rutaceae",
      "fat": 0.3,
      "genus": "Citrus",
      "id": 26,
      "name": "Lemon",
      "order": "Sapindales",
      "protein": 1.1,
      "sugar": 2.5
    },
    {
      "calories": 37,
      "carbohydrates": 9.67,
      "family": "Rutaceae",
      "fat": 0,
      "genus": "Citrus",
      "id": 98,
      "name": "Pomelo",
      "order": "Sapindales",
      "protein": 0.82,
      "sugar": 8.5
    }
  ],
  "group": "Citrus",
  "group_matched_as": [
    "genus"
  ],
  "limit": 50,
  "matched_count": 3,
  "max_value": 40,
  "min_value": null,
  "nutrient": "calories",
  "per_grams": 100,
  "sort_by": "calories",
  "sort_order": "ascending",
  "truncated": false
}
```

### Get a fruit

Look up one fruit and get its calories, fat, sugar, carbohydrate and protein per 100 grams, along with the botanical family, genus and order it belongs to. Ask by name in whatever capitalisation and spacing you have ('green apple' finds GreenApple) or by part of a name, or by catalogue number. All 49 fruits are findable by name here, including the four the service's own lookup cannot return. A name nothing matches comes back with the closest spellings rather than as a failed step.

**Inputs**

- Fruit (`fruit`, text, required): Which fruit to look up. Pick it from the list, or hand one in from an earlier step: a name in any capitalisation, with or without the spaces Fruityvice does or does not use ('green apple' finds GreenApple, 'kiwi fruit' finds Kiwifruit), part of a name when only one fruit fits it, or the catalogue number. A name that fits several fruits comes back naming them rather than picking one, and a name that fits none comes back with the closest spellings.

**Outputs**

- `calories` (number): Calories in 100 grams, empty when not recorded
- `carbohydrates` (number): Grams of carbohydrate in 100 grams, empty when not recorded
- `catalogue_count` (number): How many fruits Fruityvice holds in total
- `family` (text): The botanical family, such as Rosaceae
- `fat` (number): Grams of fat in 100 grams, empty when not recorded
- `found` (true/false): False when no fruit in the catalogue matched
- `genus` (text): The genus, such as Malus
- `id` (number): The catalogue number Fruityvice keys this fruit by
- `matched_on` (text): How it matched: 'name' for the whole name, 'id' for the catalogue number, 'name_prefix' or 'name_contains' for part of a name, 'none' when nothing matched
- `name` (text): The fruit's name, as Fruityvice publishes it
- `order` (text): The order, such as Rosales
- `per_grams` (number): How much fruit every figure above describes, which is always 100 grams
- `protein` (number): Grams of protein in 100 grams, empty when not recorded
- `query` (text): What was asked for
- `sugar` (number): Grams of sugar in 100 grams, empty when not recorded
- `suggestions` (list): The closest names in the catalogue, when nothing matched

**Example output**

```json
{
  "calories": 96,
  "carbohydrates": 22,
  "catalogue_count": 49,
  "family": "Musaceae",
  "fat": 0.2,
  "found": true,
  "genus": "Musa",
  "id": 1,
  "matched_on": "name",
  "name": "Banana",
  "order": "Zingiberales",
  "per_grams": 100,
  "protein": 1,
  "query": "Banana",
  "sugar": 17.2,
  "suggestions": []
}
```