Table of contents

Intro

On our mission to give everyone interested the knowledge on how to grow useful plants for a food garden, medicinal or regenerative uses, we want the database to be used wherever it can help. This is why we provide an API for developers to add plant data to their applications and services.

Getting access

If you want to have access, please sign up for an account and request access here.

If you have any questions or feedback, don’t hesitate to reach out to us.

Licensing

Please note that all data available through this API is licensed under CC BY-SA 4.0. That means you must provide appropriate credit (Permapeople.org), and any work built upon this dataset must be distributed under the same license (CC BY-SA 4.0). We do our best to include data sources via links, descriptions and sources within plant profiles, and encourage our contributors to do the same.

Since this is a free service, we ask that anyone using the API give attribution to plant data sources by linking back to Permapeople.org, either in a specific call-out or in plant profiles where Permapeople plant data is used.

We do not currently allow commercial projects free access to the API. If you have a commercial project and you’d like to gain access to our API, please get in touch and we can work out the details.

Please also read our data acknowledgement.

Endpoint

All following requests must be sent to and will return valid JSON (content-type: application/json; charset=utf-8).

https://permapeople.org/api

Authentication

To access all API endpoints header-based authentication must be provided for every request. To authenticate, add the following HTTP headers to your request:

x-permapeople-key-id: YOUR_KEY_ID
x-permapeople-key-secret: YOUE_KEY_SECRET

List plants

List plants ordered by their internal ID. It will return 100 plants as an array called plants.

GET https://permapeople.org/api/plants

# Response

{
  "plants" : [
    {<Plant>},
    {<Plant>},
    {<Plant>}}
    ...
  ]
}

Params

This param needs to be provided as an GET param in the URL, for example ?last_id=100.

(optional) last_id<int>: Works like a cursor and returns only plants after this id. Should be used for paging through the whole list.

(optional) updated_since<iso8601 string>: Only show plants which got updated last on or after the datetime provided.

Search plants

Returns a list of plants matching a full text search. This means it will find similar named plants too. Make sure to check the plant returned if its the right one you are looking for.

POST https://permapeople.org/api/search

# Response

{
  "plants" : [
    {<Plant>},
    {<Plant>},
    {<Plant>}}
    ...
  ]
}

Params

The param needs to be provided as a JSON object and send with content-type: application/json.

(required) q<string>: search the whole database for this term. Much like the search on the website.

Get a single plant

Returns a plant object for an exact ID.

GET https://permapeople.org/api/plants/<id>

# Response

{
   "id" : 101,
   "type" : "Plant",
   "scientific_name" : "Morus alba",
   "name" : "White mulberry",
   "version" : 10,
   "description" : "Young leaves are edible.",
   "link" : "/plants/morus-alba-white-mulberry",
   "parent_id" : null,
   "slug" : "morus-alba-white-mulberry",
   "updated_at" : "2022-07-30T08:17:26.658Z",
   "created_at" : "2020-08-11T16:09:47.485Z",
   "data" : [
      {
         "key" : "Edible",
         "value" : "true"
      },
      {
         "key" : "Growth",
         "value" : "Medium"
      },
      {
         "key" : "Water requirement",
         "value" : "Moist"
      },
      {
         "key" : "Light requirement",
         "value" : "Full sun, partial sun/shade"
      },
      {
         "key" : "USDA Hardiness zone",
         "value" : "3-9"
      },
      {
         "key" : "Layer",
         "value" : "Trees"
      },
      {
         "key" : "Soil type",
         "value" : "Light (sandy), medium, heavy (clay)"
      },
      {
         "key" : "Family",
         "value" : "Moraceae"
      },
      {
         "key" : "Edible parts",
         "value" : "Fruit, inner bark, leaves"
      }
   ]
}

Create a plant

To create za plant, do a POST request with a valid plant object. A valid plant object has as a minimum a scientific_name, name and note. On success, it will return the whole plant object or will show you an error what went wrong.

POST https://permapeople.org/api/plants

# Response

{
   "id" : 101,
   "type" : "Plant",
   "scientific_name" : "Morus alba",
   "name" : "White mulberry",
   "version" : 10,
   "description" : "Young leaves are edible.",
   "link" : "/plants/morus-alba-white-mulberry",
   "parent_id" : null,
   "slug" : "morus-alba-white-mulberry",
   "updated_at" : "2022-07-30T08:17:26.658Z",
   "created_at" : "2020-08-11T16:09:47.485Z",
   "data" : [
      {
         "key" : "Edible",
         "value" : "true"
      },
      {
         "key" : "Growth",
         "value" : "Medium"
      },
      {
         "key" : "Water requirement",
         "value" : "Moist"
      },
      {
         "key" : "Light requirement",
         "value" : "Full sun, partial sun/shade"
      },
      {
         "key" : "USDA Hardiness zone",
         "value" : "3-9"
      },
      {
         "key" : "Layer",
         "value" : "Trees"
      },
      {
         "key" : "Soil type",
         "value" : "Light (sandy), medium, heavy (clay)"
      },
      {
         "key" : "Family",
         "value" : "Moraceae"
      },
      {
         "key" : "Edible parts",
         "value" : "Fruit, inner bark, leaves"
      }
   ]
}

Params

This param needs to be provided as a JSON object and send with content-type: application/json.

(required) scientific_name<string>: The scientific name of a plant, if in doubt, use wikipedia to find the correct and current name. (required) name<string>: The common name. Here use the most common english name. (required) note<string>: Describe the action you did and what sources you used. (optional) type<enum>: Can be Plant or Variety. If Variety is used, parent_id is required and needs to be an existing plant id.

Update a plant

To update a plant, do a PUT request with the plant object fields you want to change to its own URL. On success, it will return the whole plant object or will show you an error what went wrong.

PUT https://permapeople.org/api/plants/101

# Response

{
   "id" : 101,
   "type" : "Plant",
   "scientific_name" : "Morus alba",
   "name" : "White mulberry",
   "version" : 10,
   "description" : "Young leaves are edible.",
   "link" : "/plants/morus-alba-white-mulberry",
   "parent_id" : null,
   "slug" : "morus-alba-white-mulberry",
   "updated_at" : "2022-07-30T08:17:26.658Z",
   "created_at" : "2020-08-11T16:09:47.485Z",
   "data" : [
      {
         "key" : "Edible",
         "value" : "true"
      },
      {
         "key" : "Growth",
         "value" : "Medium"
      },
      {
         "key" : "Water requirement",
         "value" : "Moist"
      },
      {
         "key" : "Light requirement",
         "value" : "Full sun, partial sun/shade"
      },
      {
         "key" : "USDA Hardiness zone",
         "value" : "3-9"
      },
      {
         "key" : "Layer",
         "value" : "Trees"
      },
      {
         "key" : "Soil type",
         "value" : "Light (sandy), medium, heavy (clay)"
      },
      {
         "key" : "Family",
         "value" : "Moraceae"
      },
      {
         "key" : "Edible parts",
         "value" : "Fruit, inner bark, leaves"
      }
   ]
}

Params

This param needs to be provided as a JSON object and send with content-type: application/json.

(required) <Plant>: the partial plant object with changed fields only. This object needs to have at minimum one changed field, the current version as int (optimistic locking) and a note as string describing the change.

Errors

If the API throws an error, it will always be an appropriate HTTP status code and valid JSON in the following format:

{
  "error": "short description",
  "msg": "longer description on what to do"
}

Help & Feedback

If you have any questions or need help using the API, feel free to reach out per mail (hello at) or on twitter. 🌱✌️ Happy coding!

Supporting free access to plant data for everyone

Since Permapeople.org is a free service, we ask that those using the Permapeople API for their own projects provide credit (to Permapeople.org) in the form of backlinks, and donate what they can. You can find donation options through our Libera Pay donations page.