Verify Plant Names

curl --request POST \
  --url https://api.superseeded.ai/v1/verify/plant-names \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form file='@example-file' \
  --form 'extraction_column=<string>'

import requests

url = "https://api.superseeded.ai/v1/verify/plant-names"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = { "extraction_column": "<string>" }
headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('extraction_column', '<string>');

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

options.body = form;

fetch('https://api.superseeded.ai/v1/verify/plant-names', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.superseeded.ai/v1/verify/plant-names",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extraction_column\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.superseeded.ai/v1/verify/plant-names"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extraction_column\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.superseeded.ai/v1/verify/plant-names")
  .header("X-API-Key", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extraction_column\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.superseeded.ai/v1/verify/plant-names")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extraction_column\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "query": {
        "submitted_name": "Eucalyptus globulus",
        "normalized_name": "eucalyptus globulus",
        "query_timestamp": "2025-01-15T10:30:00Z"
      },
      "validation": {
        "status": "validated",
        "confidence": "high",
        "consensus_score": 0.98,
        "sources_checked": 11,
        "sources_matched": 9,
        "match_summary": {
          "exact_matches": 8,
          "inexact_matches": 1,
          "no_match": 0
        }
      },
      "accepted_name": {
        "scientific_name": "Eucalyptus globulus",
        "author": "Labill.",
        "nomenclatural_status": "accepted",
        "common_names": [
          {
            "name": "Tasmanian Blue Gum",
            "language": "en",
            "region": "Global"
          }
        ],
        "taxonomic_rank": "species"
      },
      "taxonomy": {
        "kingdom": "Plantae",
        "family": "Myrtaceae",
        "genus": "Eucalyptus",
        "species": "globulus",
        "subspecies": null,
        "variety": null
      },
      "cross_references": {
        "gbif_id": "3176787",
        "wfo_id": "946382",
        "powo_id": "urn:lsid:ipni.org:names:30001419-2",
        "eol_id": "301421",
        "ala_guid": "https://id.biodiversity.org.au/taxon/apni/51440555",
        "wikidata_id": "Q159528",
        "inaturalist_taxon_id": "53398",
        "pbr_numbers": [
          "1990/106"
        ],
        "upov_code": "EUCAL_GLO"
      },
      "metadata": {
        "quality_score": 0.9,
        "api_version": "1.0.0",
        "processing_time_seconds": 4.67
      },
      "warnings": [],
      "notes": [
        "Name validated against 9 authoritative botanical databases",
        "Confirmed by: Taxonomic Name Resolution Service (WFO), Plants of the World Online (Kew Gardens), Global Biodiversity Information Facility"
      ]
    }
  ],
  "summary": {
    "total": 123,
    "validated": 123,
    "uncertain": 123,
    "not_found": 123
  }
}

Endpoints

Verify Plant Names

Validate botanical species names against 11 authoritative taxonomic databases with AI fallback. Queries GBIF, TNRS (WFO), POWO (Kew), iNaturalist, EOL, ALA, IP Australia PBR, UPOV, WikiSpecies, Wikidata, and Wikipedia in parallel. Returns unified taxonomic records with consensus scoring. Accepts input as: (1) JSON body with species_names array, (2) JSON body with file_url from TUS upload, or (3) multipart form-data with direct file upload.

POST

verify

plant-names

Verify Plant Names

curl --request POST \
  --url https://api.superseeded.ai/v1/verify/plant-names \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form file='@example-file' \
  --form 'extraction_column=<string>'

import requests

url = "https://api.superseeded.ai/v1/verify/plant-names"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = { "extraction_column": "<string>" }
headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('extraction_column', '<string>');

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

options.body = form;

fetch('https://api.superseeded.ai/v1/verify/plant-names', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.superseeded.ai/v1/verify/plant-names",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extraction_column\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.superseeded.ai/v1/verify/plant-names"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extraction_column\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.superseeded.ai/v1/verify/plant-names")
  .header("X-API-Key", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extraction_column\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.superseeded.ai/v1/verify/plant-names")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"extraction_column\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "results": [
    {
      "query": {
        "submitted_name": "Eucalyptus globulus",
        "normalized_name": "eucalyptus globulus",
        "query_timestamp": "2025-01-15T10:30:00Z"
      },
      "validation": {
        "status": "validated",
        "confidence": "high",
        "consensus_score": 0.98,
        "sources_checked": 11,
        "sources_matched": 9,
        "match_summary": {
          "exact_matches": 8,
          "inexact_matches": 1,
          "no_match": 0
        }
      },
      "accepted_name": {
        "scientific_name": "Eucalyptus globulus",
        "author": "Labill.",
        "nomenclatural_status": "accepted",
        "common_names": [
          {
            "name": "Tasmanian Blue Gum",
            "language": "en",
            "region": "Global"
          }
        ],
        "taxonomic_rank": "species"
      },
      "taxonomy": {
        "kingdom": "Plantae",
        "family": "Myrtaceae",
        "genus": "Eucalyptus",
        "species": "globulus",
        "subspecies": null,
        "variety": null
      },
      "cross_references": {
        "gbif_id": "3176787",
        "wfo_id": "946382",
        "powo_id": "urn:lsid:ipni.org:names:30001419-2",
        "eol_id": "301421",
        "ala_guid": "https://id.biodiversity.org.au/taxon/apni/51440555",
        "wikidata_id": "Q159528",
        "inaturalist_taxon_id": "53398",
        "pbr_numbers": [
          "1990/106"
        ],
        "upov_code": "EUCAL_GLO"
      },
      "metadata": {
        "quality_score": 0.9,
        "api_version": "1.0.0",
        "processing_time_seconds": 4.67
      },
      "warnings": [],
      "notes": [
        "Name validated against 9 authoritative botanical databases",
        "Confirmed by: Taxonomic Name Resolution Service (WFO), Plants of the World Online (Kew Gardens), Global Biodiversity Information Facility"
      ]
    }
  ],
  "summary": {
    "total": 123,
    "validated": 123,
    "uncertain": 123,
    "not_found": 123
  }
}

Validate botanical species names against 11 authoritative taxonomic databases with Gemini AI fallback. Returns unified taxonomic records with consensus scoring.

Overview

This endpoint queries 11 botanical databases in parallel, consolidates results using a weighted consensus algorithm, and returns a unified taxonomic record per species. Names that no source can resolve are sent to Google Gemini AI as a corrective fallback. Sources queried: GBIF, TNRS (WFO), POWO (Kew), iNaturalist, EOL, ALA, IP Australia PBR, UPOV, WikiSpecies, Wikidata, Wikipedia.

Input Options

This endpoint accepts input in three ways:

1. JSON Body with Species Names Array

curl -X POST https://api.superseeded.ai/v1/verify/plant-names \
  -H "X-API-Key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "species_names": [
      "Eucalyptus globulus",
      "Acacia melanoxylon",
      "Banksia integrifolia"
    ]
  }'

2. JSON Body with File URL (TUS Upload)

For files uploaded via TUS protocol. Names are pre-parsed by LLM, so no additional extraction is performed.

curl -X POST https://api.superseeded.ai/v1/verify/plant-names \
  -H "Authorization: Bearer <delegation_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://secure.superseeded.ai/files/abc123",
    "filename": "species_list.xlsx"
  }'

3. Direct File Upload (Multipart)

Upload files directly without TUS:

curl -X POST https://api.superseeded.ai/v1/verify/plant-names \
  -H "X-API-Key: sk_..." \
  -F "file=@plant_schedule.xlsx" \
  -F "extraction_column=Species"

Request Body (JSON)

species_names

string[]

An array of species name strings to validate. Takes precedence over file inputs.

file_url

file

URL to a previously uploaded file (from TUS storage). Names are pre-parsed via LLM.Tip: You can use the file input dialog in this playground to test with a local file.

filename

string

Original filename for context when using file_url.

extraction_column

string

Specific column name containing species names in spreadsheet files.

sources

string[]

Specific sources to query. Defaults to all 11 non-Gemini sources. Gemini is always a fallback-only source.Available: gbif, tnrs, powo, inaturalist, eol, ala, ip_australia, upov, wikispecies, wikidata, wikipedia

include_metadata

boolean

default:"true"

Include detailed taxonomic metadata in results.

cache_results

boolean

default:"true"

Cache validation results for future queries.

Form Data (Multipart Upload)

file

Direct file upload. Supports: JSON, XLSX, XLS, CSV, PDF, TXT.

extraction_column

string

Column name containing species names for spreadsheet files.

Response

The response contains an array of unified taxonomic records and a summary.

results

object[]

Array of unified taxonomic records, one per species name.

Show Unified Taxonomic Record

query

object

Query information.

Show properties

submitted_name

string

Original species name as submitted.

normalized_name

string

Lowercase, trimmed version used for matching.

query_timestamp

string

ISO 8601 timestamp of the query.

validation

object

Validation status and confidence scoring.

Show properties

status

string

Validation result: validated, uncertain, or not_found.

confidence

string

Confidence level: high, medium, or low.

consensus_score

number

0.0-1.0 score based on source agreement.

sources_checked

integer

Number of sources that returned results.

sources_matched

integer

Number of sources with a match.

match_summary

object

Counts of exact_matches, inexact_matches, no_match.

accepted_name

object

The determined correct scientific name.

Show properties

scientific_name

string

Accepted scientific name determined by weighted consensus.

author

string

Taxonomic author (e.g. “Labill.”).

nomenclatural_status

string

accepted, synonym, unresolved, or not_found.

common_names

object[]

Common names with language and region.

taxonomic_rank

string

Rank: species, subspecies, variety, etc.

taxonomy

object

Complete taxonomic classification.

Show properties

kingdom

string

Always “Plantae”.

family

string

Plant family (e.g. “Myrtaceae”).

genus

string

Genus name.

species

string

Species epithet.

subspecies

string

Subspecies if applicable.

variety

string

Variety if applicable.

cross_references

object

Database IDs for deep linking.

Show properties

gbif_id

string

GBIF taxon key.

wfo_id

string

World Flora Online ID.

powo_id

string

Plants of the World Online ID.

eol_id

string

Encyclopedia of Life page ID.

ala_guid

string

Atlas of Living Australia GUID.

wikidata_id

string

Wikidata entity ID.

inaturalist_taxon_id

string

iNaturalist taxon ID.

pbr_numbers

string[]

IP Australia PBR identifiers.

upov_code

string

UPOV variety code.

metadata

object

Processing metadata.

Show properties

quality_score

number

Overall data quality (0.0-1.0).

api_version

string

API version.

processing_time_seconds

number

Processing time.

warnings

string[]

Any data quality warnings or conflicts.

notes

string[]

Informational notes about validation.

summary

object

Batch validation summary.

Show properties

total

integer

Total species processed.

validated

integer

Count with validated status.

uncertain

integer

Count with uncertain status.

not_found

integer

Count with not_found status.

Example Response

{
  "results": [
    {
      "query": {
        "submitted_name": "Eucalyptus globulus",
        "normalized_name": "eucalyptus globulus",
        "query_timestamp": "2025-01-15T10:30:00Z"
      },
      "validation": {
        "status": "validated",
        "confidence": "high",
        "consensus_score": 0.98,
        "sources_checked": 11,
        "sources_matched": 9,
        "match_summary": {
          "exact_matches": 8,
          "inexact_matches": 1,
          "no_match": 0
        }
      },
      "accepted_name": {
        "scientific_name": "Eucalyptus globulus",
        "author": "Labill.",
        "nomenclatural_status": "accepted",
        "common_names": [
          {
            "name": "Tasmanian Blue Gum",
            "language": "en",
            "region": "Global"
          }
        ],
        "taxonomic_rank": "species"
      },
      "taxonomy": {
        "kingdom": "Plantae",
        "family": "Myrtaceae",
        "genus": "Eucalyptus",
        "species": "globulus",
        "subspecies": null,
        "variety": null
      },
      "cross_references": {
        "gbif_id": "3176787",
        "wfo_id": "946382",
        "powo_id": "urn:lsid:ipni.org:names:30001419-2",
        "eol_id": "301421",
        "ala_guid": "https://id.biodiversity.org.au/taxon/apni/51440555",
        "wikidata_id": "Q159528",
        "inaturalist_taxon_id": "53398",
        "pbr_numbers": ["1990/106"],
        "upov_code": "EUCAL_GLO"
      },
      "metadata": {
        "version": "1.0",
        "api_version": "1.0.0",
        "quality_score": 0.9,
        "processing_time_seconds": 4.67
      },
      "warnings": [],
      "notes": [
        "Name validated against 9 authoritative botanical databases",
        "Confirmed by: Taxonomic Name Resolution Service (WFO), Plants of the World Online (Kew Gardens), Global Biodiversity Information Facility"
      ]
    }
  ],
  "summary": {
    "total": 1,
    "validated": 1,
    "uncertain": 0,
    "not_found": 0
  }
}

Authentication

X-API-Key

string

Your API key for Basic/Pro plan authentication.

Authorization

string

Bearer token for Teams plan platform integration.

Supported File Formats

Format	Extension	Description
JSON	`.json`	Direct arrays of species names
Excel	`.xlsx`, `.xls`	Spreadsheets with species columns
CSV	`.csv`	Comma-separated values
PDF	`.pdf`	Text extraction from documents
Text	`.txt`	One species per line or comma-separated

Error Handling

Status Code	Description
200	Success
400	Bad request (invalid input, missing species names, invalid source)
401	Unauthorized (invalid or missing API key)
403	Forbidden (API key inactive, expired, or usage limit exceeded)
500	Internal server error

Rate Limits

API usage is tracked per API key
Each species name processed counts as 1 usage unit
Rate limits vary by subscription plan
Batch processing is more efficient for large datasets

Authorizations

X-API-Key

string

header

required

Standard API Key authentication.

Body

Object containing species names to validate or file reference.

file

File to upload. Supports: JSON, XLSX, XLS, CSV, PDF, TXT.

extraction_column

string

Column name containing species names for spreadsheet files.

Response

Successful validation with unified taxonomic records.

results

object[]

Array of unified taxonomic records, one per species

Show child attributes

summary

object

Show child attributes

Verify Pot Sizes Taxonomic Sources

​Overview

​Input Options

​1. JSON Body with Species Names Array

​2. JSON Body with File URL (TUS Upload)

​3. Direct File Upload (Multipart)

​Request Body (JSON)

​Form Data (Multipart Upload)

​Response

​Example Response

​Authentication

​Supported File Formats

​Error Handling

​Rate Limits

Authorizations

Body

Response

Overview

Input Options

1. JSON Body with Species Names Array

2. JSON Body with File URL (TUS Upload)

3. Direct File Upload (Multipart)

Request Body (JSON)

Form Data (Multipart Upload)

Response

Example Response

Authentication

Supported File Formats

Error Handling

Rate Limits