Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bniladridas/global-animal-encyclopedia
A comprehensive web application serving as a digital encyclopedia for animal species worldwide.
https://github.com/bniladridas/global-animal-encyclopedia
Last synced: about 1 month ago
JSON representation
A comprehensive web application serving as a digital encyclopedia for animal species worldwide.
- Host: GitHub
- URL: https://github.com/bniladridas/global-animal-encyclopedia
- Owner: bniladridas
- License: mit
- Created: 2024-10-19T23:40:44.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2024-10-20T00:54:06.000Z (2 months ago)
- Last Synced: 2024-10-20T05:40:51.722Z (2 months ago)
- Language: JavaScript
- Homepage: https://globalanimalencyclopedia.vercel.app
- Size: 7.85 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Global Animal Encyclopedia - Backend Documentation
| Section | Image |
|---------|-------|
| Head |  |
| Body |  |
| Tail |  |
## Overview
This project is the backend server for the Global Animal Encyclopedia, a web application that provides information about various animal species. It uses data from the Global Biodiversity Information Facility (GBIF) API to fetch and serve animal information.
## Table of Contents
- [Setup](#setup)
- [API Endpoints](#api-endpoints)
- [Data Processing](#data-processing)
- [Error Handling](#error-handling)
- [Helper Functions](#helper-functions)
- [Configuration](#configuration)
- [Deployment](#deployment)
- [Usage Examples](#usage-examples)
- [License](#license)
## Setup
### Prerequisites
- Node.js (v14 or later recommended)
- npm (comes with Node.js)
### Installation
Clone the repository:
```sh
git clone https://github.com/bniladridas/global-animal-encyclopedia.git
```
Navigate to the project directory:
```sh
cd global-animal-encyclopedia
```
Install dependencies:
```sh
npm install
```
Start the server:
```sh
npm start
```
The server will be available at `http://localhost:3000`.
### Static Files
Ensure that the favicon and other static files are accessible. The favicon is located at:
```
/public/favicon/favicon.svg
```
Make sure your server is configured to serve static files from this directory. This will allow the favicon to be displayed correctly in the browser.
## Technologies Used
## Additional Technologies
- **node-fetch**: Lightweight module that brings Fetch API to Node.js
- **GBIF API**: Global Biodiversity Information Facility API for animal data
- **Environment Variables**: For configuration management
- **HTTP/HTTPS protocols**: For API communication
## API Endpoints
### GET /api/animals
Fetch a list of animal species from the GBIF API.
#### Query Parameters:
- `offset` (optional): Starting point for pagination. Default: 0
- `limit`: Maximum number of results to return (default: 100)
#### Response:
```json
[
{
"name": "String",
"scientificName": "String",
"kingdom": "String",
"phylum": "String",
"class": "String",
"order": "String",
"family": "String",
"genus": "String",
"species": "String",
"habitat": "String",
"conservationStatus": "String",
"description": "String",
"wikiLink": "String",
"occurrences": [
{
"lat": "Number",
"lon": "Number"
}
]
}
]
```
## Data Processing
The server processes data from the GBIF API in the following ways:
1. Fetches basic animal data from GBIF.
2. For each animal, fetches occurrence data (geographic locations).
3. Transforms the data into a more usable format for the frontend.
4. Handles missing data by providing default values.
## Error Handling
The server implements error handling for API requests. If an error occurs while fetching data from GBIF, the server will respond with a 500 status code and an error message.
## Helper Functions
### fetchOccurrences(scientificName)
Fetches occurrence data for a given species.
### fetchWithRetry(url, options, retries)
Implements a retry mechanism for API requests to improve reliability.
## Configuration
- `port`: The port on which the server runs (default: 3000)
- `gbifBaseUrl`: The base URL for GBIF API requests
Consider moving these to environment variables for easier management across different environments.
## Deployment
### Heroku
To deploy the server on Heroku, follow these steps:
1. Install the Heroku CLI: [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli)
2. Log in to your Heroku account:
```sh
heroku login
```
3. Create a new Heroku app:
```sh
heroku create
```
4. Deploy the code:
```sh
git push heroku main
```
5. Open the app in your browser:
```sh
heroku open
```
### AWS
1. Set up an AWS account and install the AWS CLI: [AWS CLI](https://aws.amazon.com/cli/)
2. Configure the AWS CLI with your credentials:
```sh
aws configure
```
3. Create an Elastic Beanstalk application:
```sh
eb init
```
4. Create an environment and deploy:
```sh
eb create
eb deploy
```
### Vercel
#### Prerequisites
- Vercel account
- Vercel CLI
1. Install the Vercel CLI: [Vercel CLI](https://vercel.com/download)
2. Log in to your Vercel account:
```sh
vercel login
```
3. Deploy the project:
```sh
vercel
```
4. Follow the prompts to configure and deploy your project.
### Netlify
#### Prerequisites
- Netlify account
- Netlify CLI
1. Install the Netlify CLI: [Netlify CLI](https://docs.netlify.com/cli/get-started/)
2. Log in to your Netlify account:
```sh
netlify login
```
3. Initialize a new Netlify site:
```sh
netlify init
```
4. Deploy the project:
```sh
netlify deploy
```
5. Follow the prompts to configure and deploy your project.
### Other Platforms
Refer to the specific platform's documentation for deployment instructions.
## Usage Examples
### Fetching Animal Data
You can use `curl` or any HTTP client to test the API. Here’s an example using `curl`:
```sh
curl "http://localhost:3000/api/animals?offset=0&limit=10"
```
### Expected Response
The response will be in JSON format, similar to the structure defined in the API endpoints section.
## License
This project is licensed under the MIT License. See the [LICENSE](/LICENSE) file for details.