Guide de documentation de l’API

We will go through a fast simple example of how to plant trees using the API.

Cet article sera bientôt traduit en Français. Veuillez nous excuser pour ce désagrément.

Step 1: Request API Token.

Request the Test or Live API Token. This can be made through: https://kb.tree-nation.com/knowledge/api-availability

You will receive an email within 1 business day containing your bearer token and User ID. Here is an example:

Step 2: Load API Documentation.

Open our API Documentation. In this example, we will be running it on Postman. 

 

Step 3: Select a species to plant. 

Open our project list and select a project you're interested in. Next, click on the species tab to see the species they offer. 
Once you made your selection of the species you want to plant through the API, take note of the project and the species name. In this example, we will be planting the species 'Larix eurolepis' in the project 'Agroforesterie et Boisement, France'


Step 4: Postman - Collecting the project ID

We will start by getting the list of the projects to see the ID of the project we are interested in. This will help us later get the list of the species IDs within that project. To do so, we are going to make a GET request to https://tree-nation.com/api/projects?status=active

Next, we can CTRL+F (CMD+F for Mac) the Body to find the project in the obtained list. 

We can see here that the ID of the project is 160. Take note of the project ID.

Step 5: Postman - Collecting the species ID

The same as Step 4, but this time we will make a GET request to https://tree-nation.com/api/projects/160/species

CTRL+F (CMD+F for Mac) the species name you are looking for ('Larix eurolepis' in our case). We can see below that the ID of that species is 2052. This is a unique ID linked to that specific project, so if another project is planting the same species, it would have a different ID. So you will only need the species ID for the final step.

 

Step 6: Postman - Configure token and user ID

In the User API folder (left panel), click on POST Plant.
Go to the authorization tab and select bearer token type. Next, enter the token we provided you through email.

Head back to the Body tab, you will find an example of body that is going to be sent with a POST request to https://tree-nation.com/api/plant. 

  1. Set the name and email of the gift recipient. 
  2. Set the planter ID as your user ID provided through email.
  3. Set the Species_id to the ID you obtained in step 5.
  4. Set the message that will be included in your gift.

You will receive a response as shown above. The collect_url is the link your gift recipient will receive through email, and the certificate_url is the link to the certificate they will obtain once registering at Tree-Nation. 
Of course, in case you decide not to use our emailing system, you may let us know to deactivate the emailing from our side, and you will still receive the same API response when planting, in case you want to do your own communication.

Final Step: Check your forest to see the planted tree!