latifiss/the-african-places

A geospatial REST API for querying African places data, including cities, towns, and administrative regions with structured location endpoints. --- # 🌍 The African Places API Welcome to **The African Places API** – your programmatic gateway to discovering locations across Africa. 🚀 This backend service powers the search and geospatial features for theafricanplaces.com. It's built for performance, allowing you to search, find nearby spots, and import place data efficiently. ## ✨ Key Features - **🔍 Intelligent Search**: Full-text and regex-based search to find places by name, road, or city. - **📍 Geospatial Queries**: Find places "nearby" using MongoDB's `$near` operator or a bounding box fallback. - **⚡ Bulk Import**: Optimized, high-speed insertion of many place records directly via the MongoDB native driver. - **🗺️ Autocomplete**: Fast, prefix-based suggestions for a smooth user experience. - **🛠️ Built with TypeScript**: Fully typed for better reliability and developer experience. ## 🚀 Live Endpoints The API is hosted at: **`api.theafricanplaces.com`** For detailed, interactive documentation on all available routes, request/response formats, and examples, please visit our main website: 👉 **theafricanplaces.com *(A quick example: `GET /api/places/nearby?lat=6.5244&lon=3.3792&radius=5`)* ## 🛠️ Tech Stack - **Runtime**: Node.js - **Framework**: Express.js - **Language**: TypeScript - **Database**: MongoDB with Geospatial indexes - **ODM**: Mongoose ## 📂 Project Structure ``` . ├── controllers/ # Request handlers (places, search, nearby logic) ├── db/ # Database connection setup ├── middleware/ # Custom Express middleware ├── models/ # Mongoose data models (e.g., Place) ├── routes/ # API route definitions ├── scripts/ # Utility or maintenance scripts ├── index.ts # Application entry point └── package.json ``` ## 🧪 Local Development Follow these steps to run the API on your own machine. 1. **Clone the repository** ```bash git clone github.com cd th …