World Register of Marine Species (WoRMS) JS SDK

TypeScript SDK for accessing the World Register of Marine Species (WoRMS) APIs. Fully typed based on the official WoRMS REST API Specification.

✨ Features

• 🔷 Fully typed - Auto-generated types from WoRMS OpenAPI specification
• 📖 Automatic pagination - Handles pagination automatically for large datasets
• 🛡️ Error handling - Typed errors
• 📚 Complete - Covers all main WoRMS APIs including attributes and taxonomic ranks

🚀 Installation

npm install @koale/worms-js-sdk
# or
yarn add @koale/worms-js-sdk
# or
pnpm add @koale/worms-js-sdk

📖 Basic Usage

Example

import { WormsClient, AphiaRecord } from '@koale/worms-js-sdk';

const worms = new WormsClient();

// Use the default instance
const records = await worms.searchByScientificName("Homo sapiens");
console.log(`Found ${records.length} records`);


// Search with filters
const marineRecords = await worms.searchByScientificName("Carcharodon", {
    like: true,              // Use LIKE for partial search
    marineOnly: true,        // Only marine organisms
    extantOnly: true,        // Only non-extinct organisms
    pagination: { 
        autoIterate: true,   // Automatically collect all results
        maxResults: 100      // Limit to 100 results
    }
});

// Search by date range
const recentRecords = await worms.getRecordsByDate("2023-01-01", {
    endDate: "2023-12-31",
    marineOnly: true,
    pagination: { autoIterate: true }
});

Automatic Pagination

import { WormsClient } from '@koale/worms-js-sdk';

const worms = new WormsClient();

// Get all children of a taxon
const allChildren = await worms.getChildren(2, {
    marineOnly: true,
    pagination: { autoIterate: true }
});

// Get only the first 50 results
const firstBatch = await worms.getChildren(2, {
    pagination: { autoIterate: false },
    offset: 1
});

Detailed Information

// Get complete statistics ( this is a wrapper around the other methods, so can be slow)
const stats = await worms.getRecordStats(105838);
console.log(`Children: ${stats.childrenCount}`);
console.log(`Synonyms: ${stats.synonymsCount}`);
console.log(`Vernaculars: ${stats.vernacularsCount}`);
console.log(`Distributions: ${stats.distributionsCount}`);
console.log(`Sources: ${stats.sourcesCount}`);

// Get full record (JSON-LD format)
const fullRecord = await worms.getFullRecord(105838);
console.log(`Full record with linked data: ${fullRecord.scientificname}`);

🎯 Complete API Reference

Search Methods

| Method | Description | Pagination | |--------|-------------|-------------------| | searchByScientificName() | Search by scientific name | ✅ | | searchByVernacular() | Search by vernacular name | ✅ | | searchByScientificNames() | Batch search by scientific names | ❌ | | fuzzyMatch() | Fuzzy search with TAXAMATCH algorithm | ❌ | | getRecordsByDate() | Get records by date range | ✅ |

Records

| Method | Description | Pagination | |--------|-------------|-------------------| | getRecord() | Get record by AphiaID | ❌ | | getRecords() | Get multiple records by AphiaIDs | ❌ | | getFullRecord() | Get full record (JSON-LD) | ❌ | | getAphiaId() | Get AphiaID by name | ❌ | | getName() | Get name by AphiaID | ❌ | | exists() | Check if AphiaID exists | ❌ |

Taxonomic Hierarchy

| Method | Description | Pagination | |--------|-------------|-------------------| | getClassification() | Complete classification | ❌ | | getChildren() | Direct children | ✅ | | getSynonyms() | Synonyms | ✅ | | getVernaculars() | Vernacular names | ❌ |

Geographic & Reference Data

| Method | Description | Pagination Support | |--------|-------------|-------------------| | getDistributions() | Geographic distributions | ❌ | | getSources() | Sources and references | ❌ |

Attributes

| Method | Description | Pagination Support | |--------|-------------|-------------------| | getAttributeKeys() | Get attribute keys by ID | ❌ | | getAttributeValues() | Get attribute values by category | ❌ | | getAttributes() | Get attributes by AphiaID | ❌ | | getAphiaIdsByAttribute() | Get AphiaIDs by attribute | ✅ |

Taxonomic Ranks

| Method | Description | Pagination Support | |--------|-------------|-------------------| | getTaxonRanksById() | Get taxonomic ranks by ID | ❌ | | getTaxonRanksByName() | Get taxonomic ranks by name | ❌ | | getRecordsByTaxonRank() | Get records by taxonomic rank | ✅ |

External IDs

| Method | Description | |--------|-------------| | getExternalId() | Get external ID by AphiaID | | getRecordByExternalId() | Get record by external ID |

Supported external ID types: algaebase, bold, dyntaxa, fishbase, iucn, lsid, ncbi, tsn, gisd

Utility Methods

These are utility methods that are wrappers around the other methods.

| Method | Description | |--------|-------------| | getRecordStats() | Get complete statistics for a record | | getAllResults() | Get all results from a paginated function | | exists() | Check if an AphiaID exists |

🛡️ Error Handling

import { WormsError } from '@koale/worms-js-sdk';

try {
    const record = await worms.getRecord(999999999);
} catch (error) {
    if (error instanceof WormsError) {
        console.error(`WoRMS Error: ${error.message}`);
        console.error(`Status: ${error.status}`);
    } else {
        console.error('Unknown error:', error);
    }
}

🔧 Client Configuration

const client = new WormsClient({
    baseUrl: "https://www.marinespecies.org/rest",
    fetchOptions: {
        headers: {
            "User-Agent": "MyApp/1.0",
            "Accept": "application/json"
        },
        timeout: 10000
    }
});

📊 TypeScript Types

All types are fully typed:

import type { 
    AphiaRecord, 
    Classification, 
    Distribution, 
    Vernacular,
    Source,
    AphiaRank,
    AttributeKey,
    AttributeValue,
    Attribute,
    AphiaAttributeSet,
    AphiaRecordFull,
    WormsClientOptions,
    PaginationOptions,
    PaginatedResult,
    WormsError
} from '@koale/worms-js-sdk';

🚀 Complete Examples

Check the examples/index.ts file for complete usage examples.

Run the examples:

pnpm run example
# or
tsx examples/index.ts

📝 License

MIT License. See LICENSE for more details.

🙏 Acknowledgments

• World Register of Marine Species (WoRMS)
• WoRMS REST API
• openapi-fetch

💬 Support

For issues or questions:

• Open an issue
• Check the WoRMS API documentation