From aeb4ae568ead8d0686bf4e9e9ac4105d14e3ccb8 Mon Sep 17 00:00:00 2001 From: Magnus-SmariSma <20734986-Magnus-SmariSma@users.noreply.replit.com> Date: Thu, 20 Mar 2025 22:47:36 +0000 Subject: [PATCH] Add detailed README.md file documenting the application's features, technical stack, API configuration, and setup instructions. Improved error handling in API requests. 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 --- README.md | 210 +++++++++++++++++++++++++++++++++++++++++++++++ server/routes.ts | 17 +++- 2 files changed, 223 insertions(+), 4 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e5c0c92 --- /dev/null +++ b/README.md @@ -0,0 +1,210 @@ +# 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] \ No newline at end of file diff --git a/server/routes.ts b/server/routes.ts index 10aa8da..4e3b83a 100644 --- a/server/routes.ts +++ b/server/routes.ts @@ -275,9 +275,13 @@ export async function registerRoutes(app: Express): Promise { }); } - // Use the version endpoint which is the simplest endpoint and doesn't rely on long URLs + // Use the version endpoint which is the simplest endpoint + // This is the most reliable endpoint as it doesn't need a species name + const versionUrl = `${IUCN_BASE_URL}/version`; + try { - const response = await axios.get(`${IUCN_BASE_URL}/version`, { + // Make sure we're not including any parameters in the URL itself - only in params object + const response = await axios.get(versionUrl, { params: { token: apiKey } }); @@ -291,17 +295,18 @@ export async function registerRoutes(app: Express): Promise { return res.status(error.response.status).json({ success: false, connected: false, - message: "Failed to connect to IUCN API", + message: "Failed to connect to IUCN API: " + (error.response?.data?.message || error.message), status: error.response.status }); } throw error; } } catch (error) { + const errorMessage = error instanceof Error ? error.message : String(error); res.status(500).json({ success: false, connected: false, - message: "Error checking IUCN API status" + message: "Error checking IUCN API status: " + errorMessage }); } }); @@ -322,6 +327,7 @@ export async function registerRoutes(app: Express): Promise { if (!apiKey) { return res.status(401).json({ success: false, + connected: false, message: "IUCN API key is not configured" }); } @@ -373,6 +379,7 @@ export async function registerRoutes(app: Express): Promise { if (!apiKey) { return res.status(401).json({ success: false, + connected: false, message: "IUCN API key is not configured" }); } @@ -423,6 +430,7 @@ export async function registerRoutes(app: Express): Promise { if (!apiKey) { return res.status(401).json({ success: false, + connected: false, message: "IUCN API key is not configured" }); } @@ -473,6 +481,7 @@ export async function registerRoutes(app: Express): Promise { if (!apiKey) { return res.status(401).json({ success: false, + connected: false, message: "IUCN API key is not configured" }); }