🌍 Geo Explorer API

An educational REST API built to support interactive geography learning through learning cards, matching pairs, multiple-choice quizzes, and more.

🚀 Live Demo

👉 Access the Live API on Render

Use /api to view all available endpoints.

📖 Table of Contents

• 🌍 Geo Explorer API
  • 🚀 Live Demo
  • 📖 Table of Contents
  • 📋 Features
  • 🛠️ Tech Stack
  • 📦 Architecture
  • 📂 Database Schema
  • ✅ Getting Started
    • 🔧 Prerequisites
    • 🛠 Installation & Setup
  • 🧪 Running Tests
  • 📖 API Documentation
    • 🔑 Core Endpoints
  • 🧑‍🤝‍🧑 Credits

📋 Features

• 🗂️ Categories and subcategories for geography topics
• 🎯 Retrieve matching pairs, multiple choice, and map-based questions — filterable by level, continent, and category
• 🧠 Explore interactive learning cards with pagination and filters by continent, and subcategory
• ➕ Add new users to the platform via API
• 👤 Manage user progress, including quiz scores, levels, and custom avatars
• 🚫 Full error handling for:
  • Invalid or missing parameters
  • Non-existent routes or resources
  • SQL and data validation errors

🛠️ Tech Stack

📦 Architecture

• MVC pattern (Models, Controllers, Routers)
• Centralized error handling
• Environment-specific configuration using .env files
• Separate databases for development and test environments

📂 Database Schema

The database includes tables for users, learning_cards, categories, sub_categories, map, questions_matching_pairs, answers_matching_pairs, questions_multiple_choices and answers_multiple_choices with appropriate foreign key relationships.

✅ Getting Started

🔧 Prerequisites

• Node.js: v23.9.0 or higher
• PostgreSQL: v15 or higher

🛠 Installation & Setup

1. Clone the repository

   git clone https://github.com/Sofia-Madryha/geo-explorer-be.git
   cd geo-explorer-be

2. Install dependencies

   npm install

3. Set up environment variables

   Create three .env files in the root directory:

   For development: .env.development

   PGDATABASE=geo_explorer
   

   For testing: .env.test

   PGDATABASE=geo_explorer_test
   

   For production: .env.production

   DATABASE_URL=your_supabase_database_url
   

4. Create databases

   Ensure you have PostgreSQL installed locally and for production use a hosted solution like Supabase.

   Local PostgreSQL

   Make sure PostgreSQL is installed and running on your machine.

   👉 Download here: PostgreSQL

   Setup local database

   npm run setup-dbs

   Hosted — Using Supabase

   • Sign up at Supabase
   • Create "New Project" and retrieve your database URL

5. Seed your databases

   Seed development database

   npm run seed-dev

   Seed production database

   npm run seed-prod

6. Start the server locally

   npm start

🧪 Running Tests

Run all test suites using Jest and Supertest:

npm test

Tests include:

• ✅ Successful endpoints
• ❌ Error handling (invalid input, bad routes, PSQL violations, etc.)

📖 API Documentation

Once the server is running, you can access full API documentation at the /api endpoint.

This returns a full JSON object documenting all available endpoints, queries, and example responses.

For a better experience viewing JSON responses, install a browser extension like JSON Formatter

Alternatively, refer to the included endpoints.json file.

🔑 Core Endpoints

Method	Endpoint	Description
GET	/api	Returns JSON of all available endpoints
GET	/api/categories	Get all categories
GET	/api/subcategories	Get all subcategories
GET	/api/learning-cards	Get learning cards (supports filters: sub_category_id, continent, page)
GET	/api/users	Get all users
POST	/api/users	Create a new user
GET	/api/users/:username	Get a user by username
PATCH	/api/users/:username	Update a user (query fields like rating, level_nature, nature_quiz, etc.)
GET	/api/matching-pairs	Get matching pairs (filterable by category_id, continent, level)
GET	/api/multichoice-qa	Get multiple choice questions (filters: category_id, continent, level)
GET	/api/map	Get map-based questions

🧑‍🤝‍🧑 Credits

Created with ❤️ by Route 66 Team @ Northcoders

Team Members: Sofiia Madryha, Nayden Hristov, Wai Yan Sze, Mohammed Humadi, Catarina Sapateiro, Phone Sett Paing

---

This group project was built as part of the Software Development Bootcamp in JavaScript course provided by Northcoders to demonstrate skills in collaboration, backend development, RESTful architecture, and test-driven development.