@koale/worms-js-sdk

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