# Biodiversity API
> Match scientific or common species names to the GBIF taxonomic backbone (kingdom to species), search the global species catalogue, fetch full taxon records with vernacular names, and retrieve geo-located occurrence observations. Ideal for nature, education, research, conservation and citizen-science apps.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/biodiversity-api/..."
```

## Pricing
- **Free** (Free) — 4,000 calls/Mo, 2 req/s
- **Basic** ($8/Mo) — 80,000 calls/Mo, 6 req/s
- **Pro** ($24/Mo) — 450,000 calls/Mo, 18 req/s
- **Mega** ($69/Mo) — 2,000,000 calls/Mo, 50 req/s

## Endpoints

### Species

#### `GET /v1/match` — Match a name to taxonomy

**Parameters:**
- `name` (query, required, string) — Scientific or common name Example: `Panthera leo`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/biodiversity-api/v1/match?name=Panthera+leo"
```

**Response:**
```json
{
    "data": {
        "rank": "SPECIES",
        "class": "Mammalia",
        "genus": "Panthera",
        "order": "Carnivora",
        "family": "Felidae",
        "phylum": "Chordata",
        "status": "ACCEPTED",
        "kingdom": "Animalia",
        "matched": true,
        "species": "Panthera leo",
        "usage_key": 5219404,
        "confidence": 99,
        "match_type": "EXACT",
        "canonical_name": "Panthera leo",
        "scientific_name": "Panthera leo (Linnaeus, 1758)"
    },
    "meta": {
        "timestamp": "2026-05-30T05:06:20.736Z",
        "request_id": "a3ec1652-d77b-4557-af0b-938abf6af9e1"
    },
    "status": "ok",
    "message": "Name matched",
    "success": true
}
```

#### `GET /v1/search` — Search the species backbone

**Parameters:**
- `q` (query, required, string) — Search term Example: `oak`
- `limit` (query, optional, string) — Max 1-25 Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/biodiversity-api/v1/search?q=oak&limit=10"
```

**Response:**
```json
{
    "data": {
        "count": 10,
        "query": "oak",
        "total": 14832,
        "results": [
            {
                "key": 167121945,
                "rank": null,
                "class": "Monjiviricetes",
                "genus": "Sunrhavirus",
                "order": "Mononegavirales",
                "family": "Rhabdoviridae",
                "phylum": "Negarnaviricota",
                "status": "SYNONYM",
                "kingdom": "Orthornavirae",
                "species": "Sunrhavirus oakvale",
                "authorship": null,
                "canonical_name": null,
                "scientific_name": "Oak Vale virus",
                "vernacular_name": null
            },
            {
                "key": 304906672,
                "rank": "SPECIES",
                "class": "Alsuviricetes",
                "genus": "Blunervirus",
                "order": "Martellivirales",
                "family": "Kitaviridae",
                "phylum": "Kitrinoviricota",
                "status": "ACCEPTED",
                "kingdom": "Orthornavirae",
                "species": "Oak blunervirus 1",
                "authorship": null,
                "canonical_name": null,
                "scientific_name": "Oak blunervirus 1",
                "vernacular_name": null
            },
            {
                "key": 179903309,
                "rank": "SPECIES",
                "class": "Naldaviricetes",
                "genus": "Alphabaculovirus",
   
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/species` — Taxon record by key

**Parameters:**
- `key` (query, required, string) — Numeric taxon key Example: `5219404`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/biodiversity-api/v1/species?key=5219404"
```

**Response:**
```json
{
    "data": {
        "key": 5219404,
        "rank": "SPECIES",
        "class": "Mammalia",
        "genus": "Panthera",
        "order": "Carnivora",
        "family": "Felidae",
        "phylum": "Chordata",
        "status": "ACCEPTED",
        "kingdom": "Animalia",
        "species": "Panthera leo",
        "authorship": "(Linnaeus, 1758) ",
        "canonical_name": "Panthera leo",
        "scientific_name": "Panthera leo (Linnaeus, 1758)",
        "vernacular_name": "African lion"
    },
    "meta": {
        "timestamp": "2026-05-30T05:06:21.616Z",
        "request_id": "dd9ce56a-0dc6-4099-a839-1b6fec35cd7a"
    },
    "status": "ok",
    "message": "Species retrieved",
    "success": true
}
```

### Occurrences

#### `GET /v1/occurrences` — Occurrence observations

**Parameters:**
- `taxon_key` (query, required, string) — Numeric taxon key Example: `5219404`
- `limit` (query, optional, string) — Max 1-25 Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/biodiversity-api/v1/occurrences?taxon_key=5219404&limit=10"
```

**Response:**
```json
{
    "data": {
        "count": 10,
        "total": 18533,
        "results": [
            {
                "day": 1,
                "key": 5938104699,
                "year": 2026,
                "month": 1,
                "country": "South Africa",
                "dataset": "iNaturalist research-grade observations",
                "latitude": -24.907649,
                "locality": null,
                "longitude": 31.462346,
                "country_code": "ZA",
                "basis_of_record": "HUMAN_OBSERVATION",
                "scientific_name": "Panthera leo melanochaita (C.E.H.Smith, 1858)"
            },
            {
                "day": 3,
                "key": 5938252120,
                "year": 2026,
                "month": 1,
                "country": "South Africa",
                "dataset": "iNaturalist research-grade observations",
                "latitude": -32.35723,
                "locality": null,
                "longitude": 25.563539,
                "country_code": "ZA",
                "basis_of_record": "HUMAN_OBSERVATION",
                "scientific_name": "Panthera leo melanochaita (C.E.H.Smith, 1858)"
            },
            {
                "day": 1,
                "key": 5938302574,
                "year": 2026,
                "month": 1,
                "country": "Tanzania, United Republic of",
                "dataset": "iNaturalist research-grade observations",
                "latitude": -3.196291,
              
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/biodiversity-api
OpenAPI spec: https://www.oanor.com/api/biodiversity-api/openapi.json