WoRMS API

Free WoRMS REST API with no key: authoritative marine species names, full taxonomic hierarchy and synonym resolution for over 240,000 accepted species. Tested example included.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the WoRMS API?

The WoRMS API is a free, key-free REST interface to the World Register of Marine Species, the authoritative global register of marine organism names. It resolves species names to accepted taxa, returns the full taxonomic hierarchy from kingdom to species, and flags synonyms and unaccepted names.

Marine biology has a naming problem: the same organism is often described several times under different names, and taxonomy is revised constantly as genetic evidence accumulates. WoRMS exists to be the single authority on which name is currently accepted, maintained by a global board of taxonomic editors, and this API is the machine-readable front door to it.

The field that matters most is `status`. A record marked `accepted` is the current valid name; anything else — `unaccepted`, `alternate representation`, `nomen dubium` — means the name you searched is historical, and the `valid_AphiaID` and `valid_name` fields point at what to use instead. Following that pointer is the whole point of querying WoRMS, and skipping it is the most common mistake in downstream datasets.

Quick facts

Base URL: https://www.marinespecies.org/rest
Authentication: No API key or account. WoRMS asks that you cite the register and the retrieval date in any publication that uses the data.
Rate limit: No hard published limit. Bulk name matching should use the batch endpoints rather than one request per name.
Pricing: Free. Data is CC BY 4.0 for non-commercial use; contact WoRMS for commercial redistribution.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the WoRMS API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Look up the marine genus Solea

GET https://www.marinespecies.org/rest/AphiaRecordsByName/Solea?like=false&marine_only=true&offset=1

curl

curl 'https://www.marinespecies.org/rest/AphiaRecordsByName/Solea?like=false&marine_only=true&offset=1'

JavaScript (fetch)

const res = await fetch("https://www.marinespecies.org/rest/AphiaRecordsByName/Solea?like=false&marine_only=true&offset=1");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://www.marinespecies.org/rest/AphiaRecordsByName/Solea?like=false&marine_only=true&offset=1", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200

[
  {
    "AphiaID": 126132,
    "url": "https://www.marinespecies.org/aphia.php?p=taxdetails&id=126132",
    "scientificname": "Solea",
    "authority": "Quensel, 1806",
    "status": "accepted",
    "unacceptreason": null,
    "taxonRankID": 180,
    "rank": "Genus",
    "valid_AphiaID": 126132,
    "valid_name": "Solea",
    "valid_authority": "Quensel, 1806",
    "parentNameUsageID": 125581,
    "originalNameUsageID": null,
    "kingdom": "Animalia",
    "phylum": "Chordata",
    "class": "Teleostei",
    "order": "Pleuronectiformes",
    "family": "Soleidae",
    "genus": "Solea",
    "citation": "Froese, R. and D. Pauly. Editors. (2026). FishBase. Solea Quensel, 1806. Accessed through: World Register of Marine Species at: https://www.marinespecies.org/aphia.php?p=taxdetails&id=126132 on 2026-08-21",
    "lsid": "urn:lsid:marinespecies.org:taxname:126132",
    "isMarine": 1,
    "isBrackish": 1,
    "isFreshwater": 0,
    "isTerrestrial": 0,
    "isExtinct": null,
    "match_type": "exact",
    "modified": "2014-11-21T13:09:37.943Z"
  }
]

Parameters

Parameter	Type	Required	Description
`ScientificName`	path segment	Required	The scientific name to look up, on the `AphiaRecordsByName` endpoint. `Solea`
`like`	query	Optional	Whether to do a fuzzy `LIKE` match rather than an exact one. Defaults to true. `false`
`marine_only`	query	Optional	Restrict results to marine taxa. WoRMS also carries some non-marine records. `true`
`offset`	query	Optional	Pagination offset. Results come back 50 at a time. `1`
`AphiaID`	path segment	Optional	On the `AphiaRecordByAphiaID` endpoint, the stable numeric identifier for a taxon. `126132`

Response fields

AphiaIDinteger: Stable WoRMS identifier for the taxon — the key to use in your own database, since names change and this does not.
scientificname / authoritystring: The name and its taxonomic authority, for example "Quensel, 1806".
statusstring: `accepted` means this is the current valid name. Anything else means the name is historical and you should follow `valid_AphiaID`.
valid_AphiaID / valid_namestring: The currently accepted taxon, when the record you fetched is a synonym. Always follow this.
rank / taxonRankIDstring: Taxonomic rank of the record — Kingdom, Phylum, Class, Order, Family, Genus, Species.
kingdom / phylum / class / order / family / genusstring: The full hierarchy is flattened onto every record, so one request gives you the complete lineage.
unacceptreasonstring: Why a name was rejected, when status is not accepted. Null for accepted names.

What you can build with the WoRMS API

Validate and normalise species names in a marine biodiversity dataset
Resolve historical synonyms to the currently accepted taxon
Build a taxonomic browser for marine life
Enrich fisheries or diving records with full taxonomic hierarchy

Common errors and how to fix them

204

No content — the name matched nothing.

Fix: WoRMS returns 204 rather than 404 for an empty result, which trips up clients that only check for 200. Handle it explicitly.

400

Malformed parameters on a batch endpoint.

Fix: Batch name matching uses repeated `scientificnames[]` parameters, not a comma-separated list.

Multiple records for one name

The same name exists at different ranks or in different kingdoms.

Fix: Filter on `status == accepted` and check `rank` before picking a record.

WoRMS API — frequently asked questions

Is the WoRMS API free?

Yes, free with no API key. The data is CC BY 4.0 for non-commercial use and WoRMS asks that publications cite the register along with the date the data was retrieved; commercial redistribution needs to be arranged with them.

What does the status field mean in a WoRMS record?

It tells you whether the name is current. `accepted` is the valid name to use; `unaccepted` and similar values mean the name is a synonym or has been superseded, and the `valid_AphiaID` and `valid_name` fields name the replacement.

What is an AphiaID?

The stable numeric identifier WoRMS assigns to each taxon. Store it rather than the name, because scientific names are revised over time while the AphiaID keeps pointing at the same concept.

Why did WoRMS return HTTP 204 instead of an error?

204 No Content is how WoRMS signals that a query matched nothing. Clients that only branch on 200 versus 404 will silently mis-handle it, so check for 204 explicitly before parsing.

Tools that pair with this API

JSON to CSV Converter

Convert a JSON array of objects to CSV online. Automatic column headers from the union of all keys, delimiter choice and proper quoting — all in-browser.

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

CSV Cleaner & Deduplicator

Clean CSV online: remove duplicate rows, trim whitespace, drop empty rows and normalise the delimiter. See before/after counts — 100% in your browser.

WoRMS is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.