Species Information System

A comprehensive web application that integrates with multiple biodiversity APIs to provide detailed information about species, their conservation status, habitats, threats, and protection measures.

Overview

This application allows users to search for species using the CITES+ API and IUCN Red List API, view detailed information about them, and save this information for future reference. The system provides a unified interface to access and compare data from multiple sources, making it easier for researchers, conservationists, and wildlife enthusiasts to gather comprehensive information about species.

Features

• API Integration:

  • CITES+ API for species listings, legislation, distributions, and references
  • IUCN Red List API for conservation status, threats, habitats, and conservation measures
  • (Coming soon) GBIF for occurrence data
  • (Coming soon) Wikidata for additional taxonomic information
  • (Coming soon) SBDI Bioatlas for biodiversity data

• Search Functionality:

  • Search species by scientific name (Latin name)
  • View recent search history
  • API status indicators to confirm connections

• Detailed Species Information:

  • Basic taxonomic data (kingdom, phylum, class, order, family, genus)
  • CITES listing status and appendices
  • Geographic distribution
  • Scientific references
  • Conservation status (IUCN Red List category)
  • Threats facing the species
  • Habitat information
  • Conservation measures

• Data Management:

  • Save species information for offline access
  • View previously saved species
  • In-memory storage (with option for PostgreSQL database)

Technical Stack

• Frontend:

  • React with TypeScript
  • TanStack Query for data fetching
  • Shadcn UI components
  • Tailwind CSS for styling
  • React Hook Form for form handling

• Backend:

  • Node.js with Express
  • RESTful API architecture
  • Axios for API requests
  • Zod for validation
  • In-memory storage (with PostgreSQL option)

API Configuration

CITES+ API

The application requires a CITES+ API token for authentication. To obtain a token:

1. Visit https://api.speciesplus.net/documentation
2. Register for an account
3. Generate an API token from your account dashboard
4. Enter the token in the application's authentication panel

IUCN Red List API

The application supports both IUCN Red List API v3 and v4 versions:

IUCN API v3 (Legacy)

To use the v3 API:

1. Visit https://apiv3.iucnredlist.org/api/v3/docs
2. Register for an account and request an API key
3. The key will be automatically configured in the application's environment variables (IUCN_API_KEY)

IUCN API v4 (Recommended)

For enhanced functionality with the v4 API:

1. Visit https://apiv3.iucnredlist.org/api/v4/docs
2. Register for an account and request access to the v4 API
3. Generate a bearer token for the v4 API
4. Enter the token in the application's authentication panel (IUCN tab)

The application will intelligently use v4 if available, with automatic fallback to v3 when needed.

Getting Started

Prerequisites

• Node.js 18.x or higher
• NPM 8.x or higher

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/species-information-system.git
   cd species-information-system
   

2. Install dependencies:

   npm install
   

3. Set up environment variables: Create a .env file in the root directory and add:

   IUCN_API_KEY=your_iucn_api_key
   

4. Start the development server:

   npm run dev
   

5. Open your browser and navigate to http://localhost:5000

Using the Application

1. API Authentication:

   • Click the "API Token" button to open the authentication panel
   • In the CITES tab, enter your CITES+ API token
   • In the IUCN tab, enter your IUCN v4 bearer token (if available)
   • The API status indicators will show if both APIs are successfully connected, including which version of the IUCN API is active

2. Searching for Species:

   • Enter a scientific name (e.g., "Panthera tigris") in the search box
   • Select a species from the search results

3. Viewing Species Information:

   • Navigate through the tabs to see different categories of information
   • CITES Legislation: View protection status under CITES
   • Distribution: See geographical range of the species
   • References: View scientific publications about the species
   • IUCN Status: View conservation status and population trend
   • Threats: View factors threatening the species
   • Habitats: View habitat information
   • Conservation Measures: View protection and conservation efforts

4. Saving Species:

   • Click the "Save Species" button to store information locally
   • Access saved species from the sidebar

API Status Indicators

The application provides real-time status indicators for both APIs:

• CITES API: Shows connection status to the CITES+ API
• IUCN API: Shows connection status to the IUCN Red List API

Hovering over each indicator will show additional details about the connection status.

Error Handling

The application includes comprehensive error handling for API connections:

• Clear visual feedback when APIs are not connected
• Detailed error messages in tooltips
• Fallback to saved data when APIs are unavailable

Data Processing

To improve reliability and prevent API errors, the application processes scientific names before querying the IUCN API:

• Scientific names are simplified to genus and species components
• This prevents 414 (URI too long) errors when querying with subspecies names

Development

Project Structure

/client
  /src
    /components - UI components
    /hooks - Custom React hooks
    /lib - Utility functions and API client
    /pages - Application pages
/server
  /routes.ts - API endpoints
  /storage.ts - Data storage implementation
/shared
  /schema.ts - Shared data schemas

Adding a New API

To add a new biodiversity API:

1. Define API endpoints and response types in client/src/lib/api.ts
2. Add server routes in server/routes.ts
3. Update the API status component in client/src/components/api-status.tsx
4. Add new data display components as needed
5. Update the species tabs in client/src/components/species-tabs.tsx

Testing

Run tests with:

npm test

Limitations and Known Issues

• Some species may not have data in all API sources
• API rate limits may apply (refer to API documentation for details)
• IUCN API v3 may return 414 errors for very long scientific names (this is minimized in the implementation)
• IUCN API v4 requires a separate bearer token authentication

API Version Handling

The application intelligently manages API versions with the following approach:

• IUCN API Version Selection:

  • The system first attempts to use IUCN API v4 if a bearer token is available
  • If v4 returns an error or isn't available, the system automatically falls back to v3
  • All API responses include an apiVersion field indicating which version was used

• Version-Specific Authentication:

  • CITES+ API: Uses a token-based authentication via query parameter
  • IUCN v3: Uses an API key via environment variable and query parameter
  • IUCN v4: Uses OAuth 2.0 Bearer token authentication via headers

Future Enhancements

• Integration with GBIF, Wikidata, and SBDI Bioatlas
• Offline mode with IndexedDB storage
• Export functionality for research data
• Visualization tools for geographic distribution
• User accounts for saving preferences and searches
• Bulk data import/export features
• Mobile application version

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• CITES+ API for providing species trade and protection data
• IUCN Red List API for conservation status data
• All contributors to the biodiversity data sources used in this application

Contact

For questions, feedback, or contributions, please reach out to: [Your Contact Information]