# WoRMS Marine Species API
> The World Register of Marine Species (WoRMS) as an API — the authoritative, expert-curated taxonomic register of the world's marine life, maintained by a global network of taxonomists. WoRMS provides the accepted scientific names, naming authorities, taxonomic status and synonymy, full classification and vernacular (common) names for marine species. /v1/search?name=Orcinus orca searches species by scientific name (set fuzzy=true for partial matching, marine_only=true to restrict to marine taxa), returning each match's AphiaID (WoRMS' stable identifier), accepted name, authority, rank, taxonomic status, valid name and higher classification. /v1/species?id=137102 returns a species' full record by AphiaID — name and authority, status, the kingdom-to-genus classification, marine and brackish flags, and citation. /v1/classification?id=137102 returns the complete taxonomic tree from Biota down to the taxon, rank by rank. /v1/vernaculars?id=137102 returns the common names with their language. Get an AphiaID from /v1/search, then look up its details, tree or common names. Ideal for marine biology, fisheries science, ecology, aquaculture and biodiversity-data harmonisation. Data from WoRMS (CC BY). This is authoritative marine taxonomy and nomenclature — distinct from species-occurrence/biodiversity databases (such as GBIF) and from sequence or genome databases.

## 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/worms-api/..."
```

## Pricing
- **Free** (Free) — 2,350 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 49,500 calls/Mo, 5 req/s
- **Pro** ($20/Mo) — 219,000 calls/Mo, 12 req/s
- **Mega** ($53/Mo) — 788,000 calls/Mo, 35 req/s

## Endpoints

### Species

#### `GET /v1/classification` — Full taxonomic tree

**Parameters:**
- `id` (query, required, string) — AphiaID, e.g. 137102 Example: `137102`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/worms-api/v1/classification?id=137102"
```

**Response:**
```json
{
    "data": {
        "count": 15,
        "aphia_id": 137102,
        "classification": [
            {
                "name": "Biota",
                "rank": "Superdomain",
                "aphia_id": 1
            },
            {
                "name": "Animalia",
                "rank": "Kingdom",
                "aphia_id": 2
            },
            {
                "name": "Chordata",
                "rank": "Phylum",
                "aphia_id": 1821
            },
            {
                "name": "Vertebrata",
                "rank": "Subphylum",
                "aphia_id": 146419
            },
            {
                "name": "Gnathostomata",
                "rank": "Infraphylum",
                "aphia_id": 1828
            },
            {
                "name": "Tetrapoda",
                "rank": "Megaclass",
                "aphia_id": 1831
            },
            {
                "name": "Mammalia",
                "rank": "Class",
                "aphia_id": 1837
            },
            {
                "name": "Theria",
                "rank": "Subclass",
                "aphia_id": 380416
            },
            {
                "name": "Cetartiodactyla",
                "rank": "Order",
                "aphia_id": 370511
            },
            {
                "name": "Cetancodonta",
                "rank": "Suborder",
                "aphia_id": 370545
            },
            {
                "name": "Cetacea",
   
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search marine species by name

**Parameters:**
- `name` (query, required, string) — Scientific name, e.g. Orcinus orca Example: `Orcinus orca`
- `fuzzy` (query, optional, string) — true for partial matching
- `marine_only` (query, optional, string) — true to restrict to marine

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/worms-api/v1/search?name=Orcinus+orca"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "query": "Orcinus orca",
        "species": [
            {
                "url": "https://www.marinespecies.org/aphia.php?p=taxdetails&id=137102",
                "rank": "Species",
                "class": "Mammalia",
                "genus": "Orcinus",
                "order": "Cetartiodactyla",
                "family": "Delphinidae",
                "phylum": "Chordata",
                "status": "accepted",
                "kingdom": "Animalia",
                "aphia_id": 137102,
                "authority": "(Linnaeus, 1758)",
                "is_marine": true,
                "valid_name": "Orcinus orca",
                "is_brackish": null,
                "valid_aphia_id": 137102,
                "scientific_name": "Orcinus orca"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T16:23:23.335Z",
        "request_id": "55e75af1-dc93-4a59-aef3-e76380964f56"
    },
    "status": "ok",
    "message": "Search results retrieved",
    "success": true
}
```

#### `GET /v1/species` — A species record by AphiaID

**Parameters:**
- `id` (query, required, string) — AphiaID (from /v1/search), e.g. 137102 Example: `137102`

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

**Response:**
```json
{
    "data": {
        "species": {
            "url": "https://www.marinespecies.org/aphia.php?p=taxdetails&id=137102",
            "lsid": "urn:lsid:marinespecies.org:taxname:137102",
            "rank": "Species",
            "class": "Mammalia",
            "genus": "Orcinus",
            "order": "Cetartiodactyla",
            "family": "Delphinidae",
            "phylum": "Chordata",
            "status": "accepted",
            "kingdom": "Animalia",
            "aphia_id": 137102,
            "citation": "Fordyce, E.; Perrin, W.F. (2026). World Cetacea Database. Orcinus orca (Linnaeus, 1758). Accessed through: World Register of Marine Species at: https://www.marinespecies.org/aphia.php?p=taxdetails&id=137102 on 2026-06-01",
            "modified": "2008-08-20T11:25:36.853Z",
            "authority": "(Linnaeus, 1758)",
            "is_marine": true,
            "valid_name": "Orcinus orca",
            "is_brackish": null,
            "valid_aphia_id": 137102,
            "scientific_name": "Orcinus orca",
            "unaccept_reason": null
        }
    },
    "meta": {
        "timestamp": "2026-06-01T16:23:23.508Z",
        "request_id": "4c22b839-2567-4a85-a8b5-4a019567c82d"
    },
    "status": "ok",
    "message": "Species retrieved",
    "success": true
}
```

#### `GET /v1/vernaculars` — Common names by language

**Parameters:**
- `id` (query, required, string) — AphiaID, e.g. 137102 Example: `137102`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/worms-api/v1/vernaculars?id=137102"
```

**Response:**
```json
{
    "data": {
        "count": 106,
        "aphia_id": 137102,
        "vernaculars": [
            {
                "name": "adluk",
                "language": "Inuktitut"
            },
            {
                "name": "aguluk",
                "language": "Aleut"
            },
            {
                "name": "ardlursark",
                "language": "Kalaallisut"
            },
            {
                "name": "ardlyk",
                "language": "Kalaallisut"
            },
            {
                "name": "baleia asesina",
                "language": "Portuguese"
            },
            {
                "name": "ballena asesina",
                "language": "Spanish"
            },
            {
                "name": "ballena pinta",
                "language": "Spanish"
            },
            {
                "name": "ballena quila",
                "language": "Spanish"
            },
            {
                "name": "beom-gorae",
                "language": "Korean"
            },
            {
                "name": "botskop",
                "language": "Dutch"
            },
            {
                "name": "bovhidehval",
                "language": "Faroese"
            },
            {
                "name": "bufeo de mascarilla",
                "language": "Spanish"
            },
            {
                "name": "cahuel-huaique",
                "language": "Spanish"
            },
            {
         
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Usage notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/worms-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "WoRMS is the authoritative, expert-curated taxonomic register of the world's marine species. /v1/search?name=Orcinus orca = search species by scientific name (fuzzy=true for partial matching, marine_only=true to restrict), returning each match's AphiaID, accepted name, authority, rank, taxonomic status, valid name and higher classification; /v1/species?id=137102 = a species' full record by AphiaID — name, authority, status, the kingdom-to-genus classification, marine/brackish flags and citation; /v1/classification?id=137102 = the complete taxonomic tree from Biota down to the taxon, rank by rank; /v1/vernaculars?id=137102 = the common (vernacular) names with their language codes. AphiaID is WoRMS' stable identifier (get it from /v1/search). Data from WoRMS (CC BY). This is authoritative marine taxonomy & nomenclature — distinct from species-occurrence/biodiversity databases (GBIF) and from sequence/genome databases. Ideal for marine biology, fisheries, ecology and biodiversity-data harmonisation.",
        "source": "WoRMS — World Register of Marine Species (marinespecies.org)",
        "endpoints": [
            "/v1/search",
            "/v1/species",
            "/v1/classification",
            "/v1/vernaculars",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T16:23:23.880Z",
        "request_id": "76614337-0c7d-4e0f-8b4b-a7f53d2b5406"
    },
    "status": "ok",
    "message": "Meta retrieved",

…(truncated, see openapi.json for full schema)
```


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