
Replit-Commit-Author: Agent Replit-Commit-Session-Id: e931b5ab-041b-42e7-baf1-50017869cef6 Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/e19c6a51-7e4c-4bb8-a6a6-46dc00f0ec99/390cc67f-15c0-4fd0-85a1-9f103e918db4.jpg
210 lines
6.7 KiB
Markdown
210 lines
6.7 KiB
Markdown
# 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] |