How to?
In Brief
Pl@ntNet API provides a computational access to the visual identification engine used in
Pl@ntNet apps in the form of a RESTful Web service.
The service allows you to submit simultaneously from 1 to 5 images of the same plant and to
have in return the list of the most likely species as well as a confidence score for each of them.
The identification engine is based on most advanced deep learning technologies and is regularly updated thanks
to the contributions of the community and the integration of new expert databases.
A more detailed description of the identification engine is available in the following article:
Pl@ntnet app in the era of deep learning,
Affouard, A., Goëau, H., Bonnet, P., Lombardo, J. C., & Joly, A, ICLR 2017.
Identification performance varies from one species to another and depends mainly on the number of images illustrating them in the training database (explore here). If you would like to improve the recognition performance of a particular species, you can contribute new images using any of the Pl@ntNet apps.
The second parameter that has the greatest impact on the quality of identification is the quality of the images provided at the service input. As with Pl@ntNet apps, it is important to ensure that the images are as informative and clear as possible (see Pl@ntNet tutorial).
Getting started
Step 1 my.plantnet account
Create your account and get 500 free identification requests per day (WARNING this may take a few days, if nothing happens, please contact us).
Login to your account.
Step 2 private key
From your account, generate your private API key.
For the following example, we will use this key:
api-key: 123456
Step 3 plant pictures
Get the URLs of the images you want to identify (HTTP GET - remote images).
OR
Get the paths of the images you want to identify (HTTP POST - local images).
You can add up to 5 images in a single identification request.
WARNING Within a single request (1 to 5 images), all images must represent a single plant.For the following examples, we will use these two images:
image 1
url: https://my.plantnet.org/images/image_1.jpeg
path: /data/media/image_1.jpeg
organ: flower
image 2
url: https://my.plantnet.org/images/image_2.jpeg
path: /data/media/image_2.jpeg
organ: leaf
Step 4 data summary
Private API key:
api-key: 123456
Images:
image_1: https://my.plantnet.org/images/image_1.jpeg or /data/media/image_1.jpeg
image_2: https://my.plantnet.org/images/image_2.jpeg or /data/media/image_2.jpegEncoded URLs:
image_1: https%3A%2F%2Fmy.plantnet.org%2Fimages%2Fimage_1.jpeg
image_2: https%3A%2F%2Fmy.plantnet.org%2Fimages%2Fimage_2.jpegOrgans:
image_1: flower
image_2: leafStep 5 identification request
WARNING In the following examples, the service URL is wrong, these are just examples!
HTTP GET remote images
Identification service params:
service: https://example.identification.service
api-key: api-key=123456
image_1: images=https%3A%2F%2Fmy.plantnet.org%2Fimages%2Fimage_1.jpeg
image_2: images=https%3A%2F%2Fmy.plantnet.org%2Fimages%2Fimage_2.jpeg
organ_1: organs=flower
organ_2: organs=leafIdentification service URL:
https://example.identification.service?api-key=123456&images=https%3A%2F%2Fmy.plantnet.org%2Fimages%2Fimage_1.jpeg&images=https%3A%2F%2Fmy.plantnet.org%2Fimages%2Fimage_2.jpeg&organs=flower&organs=leaf
HTTP POST local images
Identification service params:
service: https://example.identification.service
api-key: api-key=123456
image_1: images=/data/media/image_1.jpeg
image_2: images=/data/media/image_2.jpeg
organ_1: organs=flower
organ_2: organs=leafJavaScript example:
'use strict'; const fs = require('fs'); // File System | Node.js const axios = require('axios'); // HTTP client const FormData = require('form-data'); // Readable "multipart/form-data" streams const image_1 = '/data/media/image_1.jpeg'; const image_2 = '/data/media/image_2.jpeg'; (async () => { let form = new FormData(); form.append('organs', 'flower'); form.append('images', fs.createReadStream(image_1)); form.append('organs', 'leaf'); form.append('images', fs.createReadStream(image_2)); try { const { status, data } = await axios.post( 'https://example.identification.service?api-key=123456', form, { headers: form.getHeaders() } ); console.log('status', status); // should be: 200 console.log('data', require('util').inspect(data, false, null, true)); // should be: read "Step 6" below } catch (error) { console.error('error', error); } })();
Java example:
package test; import java.io.File; import java.io.IOException; import org.apache.http.HttpEntity; import org.apache.http.HttpResponse; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.mime.MultipartEntityBuilder; import org.apache.http.entity.mime.content.FileBody; import org.apache.http.impl.client.HttpClientBuilder; import org.apache.http.util.EntityUtils; public class Test { private static final String IMAGE1 = "/data/media/image_1.jpeg"; private static final String IMAGE2 = "/data/media/image_2.jpeg"; private static final String URL = "https://example.identification.service?api-key=123456"; public static void main(String[] args) { File file1 = new File(IMAGE1); File file2 = new File(IMAGE2); HttpEntity entity = MultipartEntityBuilder.create() .addPart("images", new FileBody(file1)).addTextBody("organs", "flower") .addPart("images", new FileBody(file2)).addTextBody("organs", "leaf") .build(); HttpPost request = new HttpPost(URL); request.setEntity(entity); HttpClient client = HttpClientBuilder.create().build(); HttpResponse response; try { response = client.execute(request); String jsonString = EntityUtils.toString(response.getEntity()); System.out.println(jsonString); } catch (IOException e) { e.printStackTrace(); } } }
Python example:
import requests import json from pprint import pprint API_KEY = "123456" # Set you API_KEY here api_endpoint = f"https://my-api.plantnet.org/v2/identify/all?api-key={API_KEY}" image_path_1 = "../data/image_1.jpeg" image_data_1 = open(image_path_1, 'rb') image_path_2 = "../data/image_2.jpeg" image_data_2 = open(image_path_2, 'rb') data = { 'organs': ['flower', 'leaf'] } files = [ ('images', (image_path_1, image_data_1)), ('images', (image_path_2, image_data_2)) ] req = requests.Request('POST', url=api_endpoint, files=files, data=data) prepared = req.prepare() s = requests.Session() response = s.send(prepared) json_result = json.loads(response.text) pprint(response.status_code) pprint(json_result)
Step 6 identification results
Get the list of probable species names sorted by score.
-
result #1
- species: Hibiscus rosa-sinensis L.
- score: 0.8
-
result #2
- species: ...
- score: 0.1
-
result #...
- species: ...
- score: ...
-
result #1