> ## Documentation Index
> Fetch the complete documentation index at: https://api.superseeded.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Species Name Validation

> Validate botanical species names against 11 authoritative taxonomic databases with AI fallback

## Overview

The Species Name Validation API ensures data quality in plant schedules and botanical datasets by validating species names against 11 authoritative databases. This is essential for:

* **Plant schedule validation** before procurement
* **Data quality assurance** in botanical datasets
* **Taxonomic standardization** across different data sources
* **Compliance verification** for landscape projects

## How It Works

### Multi-Source Validation with Consensus Scoring

The API queries 11 botanical databases in parallel and consolidates the results into a single unified taxonomic record using consensus scoring.

<Steps>
  <Step title="Parallel Database Search">
    All 11 taxonomic databases are queried simultaneously for each species name.
  </Step>

  <Step title="Consensus Scoring">
    Results are consolidated using an algorithm that favours authoritative sources to determine the accepted scientific name.
  </Step>

  <Step title="AI Fallback">
    Any names with zero matches across all databases are sent to an AI model for corrective resolution of misspellings or loose descriptions.
  </Step>

  <Step title="Unified Record">
    Each species receives a single unified taxonomic record with validation status, accepted name, taxonomy, cross-references, and quality score.
  </Step>
</Steps>

### Validation Status

Each species name receives a clear validation status based on source consensus:

<CardGroup cols={3}>
  <Card title="Validated" icon="check" color="#10b981">
    **High confidence**

    Multiple sources agree on the accepted name. Ready for use in plant schedules.
  </Card>

  <Card title="Uncertain" icon="exclamation-triangle" color="#f59e0b">
    **Medium confidence**

    Some sources matched but with disagreements or only inexact matches. Requires review.
  </Card>

  <Card title="Not Found" icon="x" color="#ef4444">
    **Low confidence**

    No matches found in any database. Name likely needs correction.
  </Card>
</CardGroup>

### Quality Score

Every record includes a quality score (0.0-1.0) based on how many sources agree, how complete the taxonomic data is, and how many cross-reference IDs were found.

## Common Use Cases

### Plant Schedule Validation

The primary use case is validating botanical names in plant schedules before procurement:

```bash theme={"theme":"github-dark"}
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"
    ]
  }'
```

The response provides a clear validation summary:

* **Validated**: Proceed with confidence
* **Uncertain**: Flag for expert review
* **Not found**: Require correction before procurement

### File Upload Validation

Upload an entire plant schedule for batch validation:

```bash theme={"theme":"github-dark"}
curl -X POST https://api.superseeded.ai/v1/verify/plant-names \
  -H "X-API-Key: sk_..." \
  -F "file=@landscape_plant_schedule.xlsx" \
  -F "extraction_column=Botanical Name"
```

### Data Quality Assurance

For botanical datasets, validation identifies questionable entries:

```json theme={"theme":"github-dark"}
{
  "species_names": [
    "Eucalyptus globulus",
    "Eucalyptus globular",
    "Unknown species xyz"
  ]
}
```

* `Eucalyptus globulus` — Validated across multiple sources
* `Eucalyptus globular` — AI fallback may suggest the correct spelling
* `Unknown species xyz` — Returned as not found with warnings

## Data Sources

### Authoritative Taxonomic Databases

<CardGroup cols={2}>
  <Card title="TNRS (WFO)" icon="crown" href="https://tnrsapi.xyz">
    **World Flora Online**

    Taxonomic name validation and resolution.
  </Card>

  <Card title="POWO" icon="leaf" href="https://powo.science.kew.org">
    **Royal Botanic Gardens, Kew**

    Authoritative plant taxonomy and accepted names.
  </Card>

  <Card title="GBIF" icon="database" href="https://www.gbif.org">
    **Global Biodiversity Information Facility**

    Largest biodiversity database with vernacular names.
  </Card>

  <Card title="ALA" icon="globe" href="https://www.ala.org.au">
    **Atlas of Living Australia**

    Australian-specific plant data and occurrences.
  </Card>
</CardGroup>

### Enrichment Sources

<CardGroup cols={2}>
  <Card title="iNaturalist" icon="camera">
    Community science observations and photos.
  </Card>

  <Card title="EOL" icon="book">
    Encyclopedia of Life — species descriptions.
  </Card>

  <Card title="IP Australia PBR" icon="shield">
    Plant Breeders Rights and variety protection.
  </Card>

  <Card title="UPOV" icon="certificate">
    International plant variety protection codes.
  </Card>
</CardGroup>

### Knowledge Bases

<CardGroup cols={3}>
  <Card title="WikiSpecies" icon="sitemap">
    Wikimedia species directory.
  </Card>

  <Card title="Wikidata" icon="link">
    Structured data and images.
  </Card>

  <Card title="Wikipedia" icon="newspaper">
    General information and taxonomy.
  </Card>
</CardGroup>

### AI Fallback

<Card title="AI Correction" icon="robot">
  **Fallback only** — Used when all other sources return no match.

  Corrects misspelled or loosely described plant names. Only resolves names from the Plantae kingdom.
</Card>

## Source Roles

The consensus algorithm prioritises authoritative taxonomic databases when determining the accepted name:

| Source       | Role                    |
| ------------ | ----------------------- |
| TNRS (WFO)   | Taxonomic authority     |
| POWO (Kew)   | Botanical authority     |
| GBIF         | Biodiversity database   |
| ALA          | Regional authority (AU) |
| IP Australia | Cultivar authority      |
| UPOV         | Variety authority       |
| iNaturalist  | Observations            |
| Wikidata     | Structured data         |
| WikiSpecies  | Species directory       |
| EOL          | Encyclopedia            |
| Wikipedia    | General reference       |

## Integration Patterns

### Frontend Integration

The API implements the same validation logic as the SuperSeeded web application:

```javascript theme={"theme":"github-dark"}
const response = await fetch('/v1/verify/plant-names', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    species_names: ['Eucalyptus globulus', 'Acacia melanoxylon']
  })
});

const { results, summary } = await response.json();
console.log(`${summary.validated}/${summary.total} names validated`);
```

### Batch Processing

<Tabs>
  <Tab title="Small Datasets (< 100 species)">
    ```json theme={"theme":"github-dark"}
    {
      "species_names": ["Species 1", "Species 2", "..."]
    }
    ```

    Direct JSON submission for quick validation.
  </Tab>

  <Tab title="Large Datasets (100+ species)">
    ```bash theme={"theme":"github-dark"}
    curl -X POST https://api.superseeded.ai/v1/verify/plant-names \
      -H "X-API-Key: sk_..." \
      -F "file=@large_species_list.xlsx"
    ```

    File upload for efficient batch processing.
  </Tab>
</Tabs>

### Workflow Integration

<Steps>
  <Step title="Upload Plant Schedule">
    Designer uploads Excel/CSV file with botanical names.
  </Step>

  <Step title="Validate Species Names">
    API queries 11 databases and consolidates results with consensus scoring.
  </Step>

  <Step title="Review Flagged Items">
    System highlights uncertain or not-found names for expert review, with suggested corrections from the AI fallback.
  </Step>

  <Step title="Proceed with Procurement">
    Validated schedule with accepted names, families, and cross-references proceeds to availability checking.
  </Step>
</Steps>

## Error Handling

<Warning>
  **API Rate Limits**: Each species name counts as 1 usage unit. Monitor your usage to avoid hitting rate limits.
</Warning>

<Tip>
  **Source Failures**: If individual sources are unavailable, the API gracefully degrades and returns results from the remaining sources. Validation status reflects the available data.
</Tip>

### Error Response Examples

```json theme={"theme":"github-dark"}
{
  "detail": "No valid species names found in input"
}
```

```json theme={"theme":"github-dark"}
{
  "detail": "API Key usage limit exceeded"
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/endpoint/verify-plant-names">
    Complete technical documentation with request/response schemas.
  </Card>

  <Card title="Integration Examples" icon="puzzle-piece" href="/platform-integration/examples">
    Code examples for common integration patterns.
  </Card>
</CardGroup>