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 50 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/public/media/image_1.jpeg
    path: /data/media/image_1.jpeg
    organ: flower

    View the image

    image 2

    url: https://my.plantnet.org/public/media/image_2.jpeg
    path: /data/media/image_2.jpeg
    organ: leaf

    View the image

  • Step 4 data summary

    Private API key:

    api-key: 123456

    Images:

    image_1: https://my.plantnet.org/public/media/image_1.jpeg or /data/media/image_1.jpeg
    image_2: https://my.plantnet.org/public/media/image_2.jpeg or /data/media/image_2.jpeg

    Encoded URLs:

    image_1: https%3A%2F%2Fmy.plantnet.org%2Fpublic%2Fmedia%2Fimage_1.jpeg
    image_2: https%3A%2F%2Fmy.plantnet.org%2Fpublic%2Fmedia%2Fimage_2.jpeg

    Organs:

    image_1: flower
    image_2: leaf
  • Step 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%2Fpublic%2Fmedia%2Fimage_1.jpeg
    image_2: images=https%3A%2F%2Fmy.plantnet.org%2Fpublic%2Fmedia%2Fimage_2.jpeg
    organ_1: organs=flower
    organ_2: organs=leaf

    Identification service URL:

    https://example.identification.service?api-key=123456&images=https%3A%2F%2Fmy.plantnet.org%2Fpublic%2Fmedia%2Fimage_1.jpeg&images=https%3A%2F%2Fmy.plantnet.org%2Fpublic%2Fmedia%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=leaf

    JavaScript 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();
    		}
    	}
    }
    									
  • 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: ...