arctic-species-portal/README.md

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 requires an IUCN Red List API key for accessing conservation data. To obtain a key:

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

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:

   • Enter your CITES+ API token in the authentication panel
   • The API status indicators will show if both APIs are successfully connected

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

• IUCN API may return 414 errors for very long scientific names
• Some species may not have data in all API sources
• API rate limits may apply (refer to API documentation for details)

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]