Documentation

DWC routes

Pl@ntNet API provides a set of "DarwinCore-like" routes for observations and plots data sharing.

General information

A Pl@ntNet observation is a JSON document that represents an occurrence of a plant species associated to one or more images, AI identification results, and various metadata.

A Pl@ntNet plot is a JSON document that represents a survey of multiple plant species associated to a single image (usually a quadrat), AI identification results, and various metadata.

Observations and plots shared through these routes are under Creative Commons license, mostly CC BY-SA. According to the license, you are allowed to reuse and share Pl@ntNet observations and plots on the condition that you cite the author, the license, and "Pl@ntNet" as the data source.

Ouput format is JSON, with a content based on most relevant DarwinCore fields.

Input parameters and URL format are based on GBIF "occurrence" API.

*/search routes provide a paginated stream of data allowing to find latest data matching different criteria. To this end, occurrences returned (whether observations or plots) are always sorted by creation date.

The creation date of an occurrence might differ from its observation date, but can never be earlier.

*/{id} routes provide details about an element given its id.

Routes list

  • /v2/dwc/occurrence/search
    • Returns observations occurrences matching the input criteria
  • /v2/dwc/occurrence/{id}
    • Returns details about an observation occurrence
  • /v3/dwc/occurrence/search (POST)
    • Returns observations occurrences matching the input criteria, improved version
  • /v3/dwc/plot/search (POST)
    • Returns plots occurrences matching the input criteria

See OpenAPI doc for details.

Input

Pagination

There are 2 ways to paginate results.

Set page to an integer >= 1 to paginate by 100 items.

When using page parameter, page numbers start at 1, not 0.

Otherwise, set offset to an integer >= 0 and limit to an integer >= 1 to control pagination more precisely, respectively data count to skip and page size.

page parameter has precedence over offset / limit couple.

Additionnaly, set startTime to a millisecond timestamp to ensure no data created after this date is returned. This prevents pagination shift by freshly added data, when sorting by date decreasing.

startTime is related to decreasing dates order, it should be understood as "highest date value".

Set hasIdentification to true to ensure returned occurrences are associated to a valid species name that matches Pl@ntNet referentials.

Set taxonID to 0 to return unidentified occurrences only.

Set taxonKey to any GBIF taxon_key value to get occurrences of this taxon only; set it to 0 to return unidentified occurrences only.

identificationVerificationStatus accepts 2 values:

  • casual will return non-valid occurrences only
  • research will return valid occurrences only

A Pl@ntNet occurrence is considered valid when the confidence in its determination exceeds a certain threshold.

Set scientificName to one or more binomial plant species names (separated by , in a single string) to get occurrences of these species only.

/v2/dwc/observations/search route only supports a single scientificName.

When scientificNameMatchCase is false, scientificName accepts names whatever the case, notably lowercase (ex: acer campestre).

When scientificNameMatchAuthor is true, scientificName expects species names including authorship (ex: Acer campestre L.); otherwise names without authorship are expected (ex: Acer campestre).

Set hasCoordinate to true to get only data having a geolocation information, or to false to get only data having no geolocation information.

Set all 4 parameters minDecimalLongitude, maxDecimalLongitude, minDecimalLatitude and maxDecimalLatitude to WGS84 decimal coordinates to define a bounding box and get only geolocated data present inside this bounding box.

Set geometry to the geometry part of a GeoJSON Polygon or MultiPolygon to get only geolocated data present inside this (Multi)Polygon.

Coordinate pairs describing a Polygon must be declared counter-clockwise, aka. "the right-hand rule".

Set minEventDate and maxEventDate to either millisecond timestamps or YYYY-MM-DD strings to restrict returned data to occurrences created in this time range. Both parameters can be used individually.

When using YYYY-MM-DD format, time boundary is set to YYYY-MM-DDT00:00:00.000Z.

Additionnaly, set startTime to a millisecond timestamp to ensure no data created after this date is returned − see "Pagination" above.

/v2/dwc/observations/search route only supports YYYY-MM-DD format for minEventDate and maxEventDate.

Other input parameters

Set lang to a language code returned by /v2/languages route to get contextualized results, such as common names.

Set license to one or more licence values (separated by , in a single string) to restrict returned occurrences to those shared under these licenses.

Ouput format

Output of */search routes is of the following form.

{
  "offset": 0,
  "limit": 100,
  "startTime": 1739100783208,
  "endOfRecords": false,
  "results": [
  ]
}

offset and limit give the pagination status.

startTime gives the most recent occurrence date, to be reused in startTime parameter to prevent pagination shift if needed (see "Input" above).

An endOfRecords value of false indicates that more results exist matching your input filters.

See Using images to learn about images reuse and citation.

cURL examples

GET /v2/dwc/occurrence/search

curl 'https://my-api.plantnet.org/v2/dwc/occurrence/search?api-key=YOUR_API_KEY'

{
  "offset": 0,
  "limit": 100,
  "startTime": 1739373734878,
  "endOfRecords": false,
  "results": [
    {
      "id": "1025714101",
      "eventDate": "2025-02-12T15:22:14.878Z",
      "observedOn": "2025-02-12T15:21:54.000Z",
      "scientificName": "Kalanchoe blossfeldiana Poelln.",
      "ownerInstitutionCodeProperty": "Pl@ntNet",
      "identificationVerificationStatus": "research",
      "basisOfRecord": "LIVING_SPECIMEN",
      "type": "StillImage",
      "accessRight": "",
      "license": "CC-BY-SA",
      "rightsHolder": "Rod76230",
      "taxon": {
        "id": 2985944,
        "rank": "species",
        "rank_level": 10,
        "kingdom": "Plantae",
        "family": "Crassulaceae",
        "name": "Kalanchoe blossfeldiana Poelln.",
        "url": "https://identify.plantnet.org/fr/k-world-flora/species/Kalanchoe%20blossfeldiana%20Poelln./data",
        "common_names": {
          "en": [
            "Flaming katy",
            "Madagascar widow's-thrill",
            "Flaming Katie",
            "Christmas kalanchoe"
          ]
        }
      },
      "occurrenceStatus": "PRESENT",
      "media": [
        {
          "type": "StillImage",
          "format": "image/jpeg",
          "identifier": "44fac0688b2e21bcebad7e95d0627868a8e1cbfa",
          "medium_url": "https://bs.plantnet.org/image/m/44fac0688b2e21bcebad7e95d0627868a8e1cbfa",
          "large_url": "https://bs.plantnet.org/image/o/44fac0688b2e21bcebad7e95d0627868a8e1cbfa",
          "organ": "flower"
        }
      ],
      "user": {
        "id": "101150230"
      },
      "identifications": [],
      "votes": [
        {
          "determination": "Kalanchoe blossfeldiana Poelln.",
          "count": 1,
          "score": 4.91
        }
      ],
      "comments": [],
      "decimalLatitude": 49.4562316554,
      "decimalLongitude": 1.1045087901,
      "privateGeolocation": false,
      "elevation": 148.105,
      "geolocationAccuracy": 9.6107961772
    },
    (…)
  ]
}

GET /v2/dwc/occurrence/{id}

curl 'https://my-api.plantnet.org/v2/dwc/occurrence/1025714101?api-key=YOUR_API_KEY'

{
  "id": "1025714101",
  "eventDate": "2025-02-12T15:22:14.878Z",
  "observedOn": "2025-02-12T15:21:54.000Z",
  "scientificName": "Kalanchoe blossfeldiana Poelln.",
  "ownerInstitutionCodeProperty": "Pl@ntNet",
  "identificationVerificationStatus": "research",
  "basisOfRecord": "LIVING_SPECIMEN",
  "type": "StillImage",
  "accessRight": "",
  "license": "CC-BY-SA",
  "rightsHolder": "Rod76230",
  "taxon": {
    "id": 2985944,
    "rank": "species",
    "rank_level": 10,
    "kingdom": "Plantae",
    "family": "Crassulaceae",
    "genus": "Kalanchoe",
    "name": "Kalanchoe blossfeldiana Poelln.",
    "url": "https://identify.plantnet.org/fr/k-world-flora/species/Kalanchoe%20blossfeldiana%20Poelln./data",
    "common_names": {
      "en": [
        "Flaming katy",
        "Madagascar widow's-thrill",
        "Flaming Katie",
        "Christmas kalanchoe"
      ]
    }
  },
  "occurrenceStatus": "PRESENT",
  "media": [
    {
      "type": "StillImage",
      "format": "image/jpeg",
      "identifier": "44fac0688b2e21bcebad7e95d0627868a8e1cbfa",
      "medium_url": "https://bs.plantnet.org/image/m/44fac0688b2e21bcebad7e95d0627868a8e1cbfa",
      "large_url": "https://bs.plantnet.org/image/o/44fac0688b2e21bcebad7e95d0627868a8e1cbfa",
      "organ": "flower"
    }
  ],
  "user": {
    "id": "101150230"
  },
  "identifications": [
    {
      "createdAt": "2025-02-12T15:22:14.819Z",
      "updatedAt": "2025-02-12T15:22:14.819Z",
      "taxon": {
        "id": 2985944,
        "rank": "species",
        "rank_level": 10,
        "kingdom": "Plantae",
        "family": "Crassulaceae",
        "genus": "Kalanchoe",
        "name": "Kalanchoe blossfeldiana Poelln.",
        "common_names": {
          "en": [
            "Flaming Katie",
            "Madagascar Widow's-Thrill",
            "Madagascar widow's-thrill",
            "flaming katy",
            "Flaming Katy"
          ],
          "fr": [
            "Kalanchoë des fleuristes"
          ],
          "pt": [
            "kalanchoe"
          ],
          "sv": [
            "våreld",
            "höstglöd"
          ]
        }
      },
      "score": 0.63284
    }
  ],
  "votes": [
    {
      "determination": "Kalanchoe blossfeldiana Poelln.",
      "count": 1,
      "score": 4.91
    }
  ],
  "comments": [],
  "decimalLatitude": 49.4562316554,
  "decimalLongitude": 1.1045087901,
  "privateGeolocation": false,
  "elevation": 148.105,
  "geolocationAccuracy": 9.6107961772
}

POST /v3/dwc/occurrence/search

curl -X POST 'https://my-api.plantnet.org/v3/dwc/occurrence/search?api-key=YOUR_API_KEY'

{
  "offset": 0,
  "limit": 100,
  "startTime": 1739372251160,
  "endOfRecords": false,
  "results": [
    {
      "id": "1025713958",
      "eventDate": "2025-02-12T14:57:31.160Z",
      "observedOn": "2025-02-12T14:55:10.547Z",
      "scientificName": "Pterospermum acerifolium (L.) Willd.",
      "ownerInstitutionCodeProperty": "Pl@ntNet",
      "identificationVerificationStatus": "casual",
      "basisOfRecord": "LIVING_SPECIMEN",
      "type": "StillImage",
      "accessRight": "",
      "license": "CC-BY-SA",
      "rightsHolder": "Altaf Shaikh",
      "taxon": {
        "id": 3669210,
        "rank": "species",
        "rank_level": 10,
        "kingdom": "Plantae",
        "family": "Malvaceae",
        "name": "Pterospermum acerifolium (L.) Willd.",
        "url": "https://identify.plantnet.org/fr/k-indian-subcontinent/species/Pterospermum%20acerifolium%20(L.)%20Willd./data",
        "common_names": {
          "en": [
            "Dinner plate tree",
            "Maple-leaved bayur"
          ]
        }
      },
      "occurrenceStatus": "PRESENT",
      "media": [
        {
          "type": "StillImage",
          "format": "image/jpeg",
          "identifier": "ff76124c3157ce5d0a12e0a49b2619c29d22af42",
          "medium_url": "https://bs.plantnet.org/image/m/ff76124c3157ce5d0a12e0a49b2619c29d22af42",
          "large_url": "https://bs.plantnet.org/image/o/ff76124c3157ce5d0a12e0a49b2619c29d22af42",
          "organ": "leaf"
        }
      ],
      "user": {
        "id": "108757898"
      },
      "identifications": [],
      "votes": [
        {
          "determination": "Pterospermum acerifolium (L.) Willd.",
          "count": 1,
          "score": 0.74
        }
      ],
      "comments": []
    },
    (…)
  ]
}

POST /v3/dwc/plot/search

curl -X POST 'https://my-api.plantnet.org/v3/dwc/plots/search?api-key=YOUR_API_KEY'

{
  "offset": 0,
  "limit": 100,
  "startTime": 1739100783208,
  "endOfRecords": false,
  "results": [
    {
      "id": "57300276804",
      "eventDate": "2025-02-09T11:33:03.208Z",
      "observedOn": "2025-01-22T12:22:07.000Z",
      "title": "MDGTN20250122MR6.5",
      "description": null,
      "ownerInstitutionCodeProperty": "Pl@ntNet",
      "basisOfRecord": "LIVING_SPECIMEN",
      "type": "StillImage",
      "accessRight": "",
      "license": "CC-BY-SA",
      "rightsHolder": "mampionona manampy",
      "species": [
        {
          "name": "Cyperus niveus Retz.",
          "organismQuantity": 2,
          "organismQuantityType": "%Coverage",
          "organs": [
            "leaf",
            "habit"
          ],
          "taxon": {
            "id": 2716380,
            "rank": "species",
            "rank_level": 10,
            "kingdom": "Plantae",
            "family": "Cyperaceae",
            "name": "Cyperus niveus Retz.",
            "url": "https://identify.plantnet.org/fr/undefined/species/Cyperus%20niveus%20Retz./data",
            "common_names": {
              "en": []
            },
            "iucn_red_list_category": null
          }
        },
        {
          "name": "Tolpis capensis (L.) Sch.Bip.",
          "organismQuantity": 8,
          "organismQuantityType": "%Coverage",
          "organs": [
            "leaf",
            "habit"
          ],
          "taxon": {
            "id": 3097153,
            "rank": "species",
            "rank_level": 10,
            "kingdom": "Plantae",
            "family": "Asteraceae",
            "name": "Tolpis capensis (L.) Sch.Bip.",
            "url": "https://identify.plantnet.org/fr/undefined/species/Tolpis%20capensis%20(L.)%20Sch.Bip./data",
            "common_names": {
              "en": []
            },
            "iucn_red_list_category": null
          }
        },
        {
          "name": "Crotalaria retusa L.",
          "organismQuantity": 3,
          "organismQuantityType": "%Coverage",
          "organs": [
            "leaf",
            "habit"
          ],
          "taxon": {
            "id": 2942610,
            "rank": "species",
            "rank_level": 10,
            "kingdom": "Plantae",
            "family": "Fabaceae",
            "name": "Crotalaria retusa L.",
            "url": "https://identify.plantnet.org/fr/undefined/species/Crotalaria%20retusa%20L./data",
            "common_names": {
              "en": [
                "Rattlebox",
                "Devil-bean",
                "Wedge-leaf crotalaria",
                "Wedge-leaf rattlepod",
                "Rattleweed",
                "Rattlepod",
                "Big Yellow Popbush",
                "Yellow rattlebox",
                "Wedgeleaf rattlebox",
                "Wedgeleaf rattlepod"
              ]
            },
            "iucn_red_list_category": null
          }
        },
        {
          "name": "Sida rhombifolia L.",
          "organismQuantity": 10,
          "organismQuantityType": "%Coverage",
          "organs": [
            "leaf",
            "habit"
          ],
          "taxon": {
            "id": 5406735,
            "rank": "species",
            "rank_level": 10,
            "kingdom": "Plantae",
            "family": "Malvaceae",
            "name": "Sida rhombifolia L.",
            "url": "https://identify.plantnet.org/fr/undefined/species/Sida%20rhombifolia%20L./data",
            "common_names": {
              "en": [
                "Cuban-jute",
                "Queensland-hemp",
                "Broomjue sida",
                "Paddy-lucerne",
                "Arrowleaf sida",
                "Teaweed",
                "Common sida",
                "Sida-retusa",
                "Sidaweed",
                "Sidratusa",
                "Selegui",
                "Tagghuri",
                "Cuba jute",
                "Arrow-leaf Sida",
                "Axocatzín",
                "Rhombic-leaved sida",
                "Rhomboid ilima",
                "Broomweed"
              ]
            },
            "iucn_red_list_category": null
          }
        },
        {
          "name": "Coincya monensis",
          "organismQuantity": 3,
          "organismQuantityType": "%Coverage",
          "organs": [
            "leaf",
            "habit"
          ]
        },
        {
          "name": "Cynodon dactylon (L.) Pers.",
          "organismQuantity": 25,
          "organismQuantityType": "%Coverage",
          "organs": [
            "leaf",
            "habit"
          ],
          "taxon": {
            "id": 6109637,
            "rank": "species",
            "rank_level": 10,
            "kingdom": "Plantae",
            "family": "Poaceae",
            "name": "Cynodon dactylon (L.) Pers.",
            "url": "https://identify.plantnet.org/fr/undefined/species/Cynodon%20dactylon%20(L.)%20Pers./data",
            "common_names": {
              "en": [
                "Bermuda grass",
                "Green couch",
                "Plain couch",
                "Common couch",
                "Indian couch",
                "Bahama Grass",
                "Brakgras Salu",
                "Dog's-tooth grass",
                "Indian doab",
                "Couch grass",
                "Devil's grass",
                "Dubo",
                "Scutch grass"
              ]
            },
            "iucn_red_list_category": null
          }
        },
        {
          "name": "Oplismenus undulatifolius (Ard.) P.Beauv.",
          "organismQuantity": 30,
          "organismQuantityType": "%Coverage",
          "organs": [
            "leaf",
            "habit"
          ],
          "taxon": {
            "id": 7745203,
            "rank": "species",
            "rank_level": 10,
            "kingdom": "Plantae",
            "family": "Poaceae",
            "name": "Oplismenus undulatifolius (Ard.) P.Beauv.",
            "url": "https://identify.plantnet.org/fr/undefined/species/Oplismenus%20undulatifolius%20(Ard.)%20P.Beauv./data",
            "common_names": {
              "en": [
                "Wavy-leaf basketgrass",
                "Wavyleaf basketgrass",
                "Australian basketgrass",
                "Creeping beardgrass",
                "Slender panicgrass",
                "Spicate armgrass"
              ]
            },
            "iucn_red_list_category": null
          }
        }
      ],
      "occurrenceStatus": "PRESENT",
      "media": [
        {
          "type": "StillImage",
          "format": "image/jpeg",
          "identifier": "f627a74ad7d4ee722f203d52c71206c517783ae2",
          "large_url": "https://bs.plantnet.org/image/hd/f627a74ad7d4ee722f203d52c71206c517783ae2"
        }
      ]
    },
    (…)
  ]
}