# 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](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](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]