Documentation

Multi-species survey identification

Pl@ntNet API provides a set of routes for multi-species identification, also called "survey", "quadrat" or "plot" routes.

Multi-species survey identification is available in beta. Access is currently limited: if you’d like to use this feature, please contatc us with a brief description of your use case. We’ll review your request and determine whether it fits our current beta program.

General information

Plant biodiversity surveys are essential for ecological studies, enabling standardized sampling, biodiversity assessment, longterm monitoring and remote, large-scale surveys. However, inventoring all plant species in a given plot is a very costly process, even when using Pl@ntNet app. Thse routes aim at automatizing the identification of all plants visible in high-resolution images such as vegetation quadrat images (Overview of PlantCLEF 2024: multi-species plant identification in vegetation plot images, Goëau, H., Espitalier, V., Bonnet, P., Joly A., 2024), drone images of roadside views (From Species Identification to Species Presence Detection in High Resolution Images - an Application to Invasive Plant Species Using Roadside Views, Espitalier, V., Goëau, H., Botella, C., Dyrmann, M., Hoye, T., Bonnet, P., Joly, A., 2024). It is important to note that the performance is currently lower than that obtained with a classic single-plant observation (as discussed in Goëau, H. et al., 2024). However, the performance of this service will raise over time thanks to the improvement of the models and the integration of new training data.

Multi-species identification uses single-species identification AI model along with a tiling process, to detect multiple plant species in a single image.

Only a single image can be sent per request. Only images with image/jpeg or image/png mimetype are allowed, and image size cannot exceed 50 MB.

Multi-species identification costs 1 credit per tile.

Depending on input parameters, a single survey identification request might consume a lot of credits from your quota. Requests that would exceed your quota will be denied with a 429 error code. You can also estimate the cost using /v2/survey/cost route before sending the request.

Routes list

  • /v2/survey/tiles/{project}
    • Identify multiple plant species in a plot image
  • /v2/cost/survey/{project}
    • Estimate cost before sending identification request

See OpenAPI doc for details.

Cost estimation

/v2/cost/survey route shares parameters with /v2/survey/tiles.

When running multi-species identification, one sub-query is processed for each tile. Cost estimation thus calculates the number of tiles depending on the input image size and parameters such as tile_size, tile_stride, etc. Be sure to call /v2/cost/survey with the same values you're about to pass to /v2/survey/tiles for all parameters they have in common.

Cost estimation does not accept an input file, but instead expects the image size in pixels in the form "3200x2400". This is to avoid processing the image file, whose content is not necessary for cost estimation.

Input

Project

Also known as "floras" or "referentials", "projects" are lists of species-level taxa, related to a geographical area or a theme.

Set project to any value from /v2/projects.

Multi-species identification does not support legacy projects.

Image

image is a binary file, in JPG or PNG format. You can submit only one image per request.

Ideal candidate image is a "quadrat" or "plot" picture, ie. a picture of a square land area taken from above, for a surface between 0.25 m² and 1m².

Set tile_size to an integer value > 0 to define the size of a tile (a sub-query). When using multi-scale option, this defines the minimum size of a tile.

tile_size values that are too small will be ignored. Minimum value for tile_size depends on the current model's input size and is subject to change (518px in May 2025).

Set tile_stride to an integer value > 0 to define the image sampling (x/y translation from one tile to another).

Set multi_scale to true to enable multi-scale analysis and generate tiles of different sizes according to size_factor.

Set size_factor to a float value > 0 to define multiplicative factor applied to 2 successive tile sizes (applicable only when multi_scale is true).

Set pyramid to true to generate pyramids of tiles centered on a set of pixels (applicable only when multi_scale is true).

Set min_score to a float value > 0 to restrict results to confidence scores exceeding this threshold.

Set max_rank to an integer value > 1 to restrict results to top-n rank.

Set multi_scale_coverage to true to compute coverage using results from all zoom levels, and not only the finest one (applicable only when multi_scale is true).

Set show_species to true to get per-species results.

Set show_genus to true to get per-genus results.

Set show_family to true to get per-family results.

You should have at least one of show_species, show_genus or show_family set to true.

Set detailed_reject to true to include more information about non-plant results, if any.

Ouput format

Output is of the following form.

{
  "status": "OK",
  "query": {
    "project": "k-world-flora",
    "stats": {}
  },
  "results": {
    (…)
    "nb_sub_queries": 100,
    "nb_matching_sub_queries": 77,
    "uncovered": 0.36364,
    "species": []
  },
  "version": "2025-01-17 (7.3)"
}

query summarizes input.

results gives stats about the number of sub-queries executed, and how many of them gave results.

results.species is the list of predicted probable plant species, by order of coverage decreasing. Additional information for each species include: coverage ratio, highest confidence score among matching tiles, number of matching tiles, and the list of matching tiles with position, confidence score and detected organ.

version gives the version of the AI engine that processed your request.

cURL examples

POST /v2/cost/survey

curl -X POST 'https://my-api.plantnet.org/v2/cost/survey/k-world-flora?api-key=YOUR_API_KEY' -F "size=3024x3024"

{
  "estimated_cost": 100,
  "query": {
    "project": "k-world-flora",
    "images": [],
    "organs": [],
    "filters": [],
    "exclude": [],
    "what": "QUADRAT",
    "family_check": false,
    "genus_check": false,
    "reject_type": "ALL",
    "ignore_reject": [],
    "knn_classif": {
      "variety": true
    },
    "flavor": "tiles",
    "tile_size": 518,
    "tile_stride": 259,
    "multi_scale": false,
    "size_factor": 1.4142135623730951,
    "pyramid": false,
    "min_score": 0.1,
    "max_rank": 1,
    "stats": {
      "all": 0.000277945,
      "download": 0,
      "extract": 0,
      "post-process": 0,
      "pre-process": 0.000160118,
      "process": 0,
      "simsearch": 0,
      "wait-download": 0,
      "wait-extract": 0,
      "wait-simsearch": 0,
      "from": "partner",
      "image_source": "",
      "method": "get",
      "nb_images": "0",
      "route": "v2",
      "status": "",
      "type": "quadrat"
    }
  }
}

POST /v2/cost/survey/tiles

curl -X POST 'https://my-api.plantnet.org/v2/survey/tiles/k-world-flora?api-key=YOUR_API_KEY' -F image=@/path/to/plot_image.jpg

{
  "status": "OK",
  "query": {
    "project": "k-world-flora",
    (…)
  },
  "results": {
    "tile_size": 518,
    "tile_stride": 259,
    "nb_sub_queries": 100,
    "nb_matching_sub_queries": 77,
    "uncovered": 0.36364,
    "image": {
      "name": "",
      "width": 3024,
      "height": 3024,
      "nb_sub_queries": 100,
      "nb_matching_sub_queries": 77,
      "uncovered": 0.36364
    },
    "species": [
      {
        "name": "Juncus effusus L.",
        "id": "1363328",
        "gbif_id": "2701311",
        "binomial": "Juncus effusus",
        "author": "L.",
        "genus": "Juncus",
        "family": "Juncaceae",
        "coverage": 0.21488,
        "max_score": 0.33556,
        "count": 14,
        "location": [
          {
            "center": {
              "x": 1382,
              "y": 1123
            },
            "size": 518,
            "score": 0.13511,
            "organ": "leaf"
          },
          {
            "center": {
              "x": 1382,
              "y": 1382
            },
            "size": 518,
            "score": 0.15142,
            "organ": "bark"
          },
          {
            "center": {
              "x": 1382,
              "y": 2418
            },
            "size": 518,
            "score": 0.31905,
            "organ": "leaf"
          },
          {
            "center": {
              "x": 1641,
              "y": 1123
            },
            "size": 518,
            "score": 0.19646,
            "organ": "leaf"
          },
          {
            "center": {
              "x": 1641,
              "y": 1382
            },
            "size": 518,
            "score": 0.26909,
            "organ": "leaf"
          },
          {
            "center": {
              "x": 1641,
              "y": 2159
            },
            "size": 518,
            "score": 0.19816,
            "organ": "bark"
          },
          (…)
        ]
      },
      {
        "name": "Rubus saxatilis L.",
        "id": "1395601",
        "gbif_id": "2992808",
        "binomial": "Rubus saxatilis",
        "author": "L.",
        "genus": "Rubus",
        "family": "Rosaceae",
        "coverage": 0.07438,
        "max_score": 0.50027,
        "count": 3,
        "location": [
          {
            "center": {
              "x": 1900,
              "y": 2418
            },
            "size": 518,
            "score": 0.12995,
            "organ": "leaf"
          },
          {
            "center": {
              "x": 1900,
              "y": 2677
            },
            "size": 518,
            "score": 0.37654,
            "organ": "leaf"
          },
          {
            "center": {
              "x": 2418,
              "y": 2677
            },
            "size": 518,
            "score": 0.50027,
            "organ": "leaf"
          }
        ]
      },
      (…)
    ]
  },
  "version": "2025-01-17 (7.3)"
}