https://github.com/txuli/geohub-api
A simple API providing information about cities and countries.
https://github.com/txuli/geohub-api
api-country bun country-list express
Last synced: 22 days ago
JSON representation
A simple API providing information about cities and countries.
- Host: GitHub
- URL: https://github.com/txuli/geohub-api
- Owner: txuli
- License: other
- Created: 2026-01-19T20:05:33.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-09T16:12:17.000Z (about 2 months ago)
- Last Synced: 2026-05-09T17:41:22.964Z (about 2 months ago)
- Topics: api-country, bun, country-list, express
- Language: TypeScript
- Homepage: https://geohub.com
- Size: 102 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GeoHub API
A RESTful API for discovering countries and cities worldwide, with geolocation features and Wikipedia data integration.
## Overview
Finda.city is a geographic data API that provides information about countries and cities around the world. It features IP-based geolocation, proximity search, and integrates with Wikipedia to provide enriched data about locations.
## Features
- 🌍 **Country Information**: Get data about countries including population, life expectancy, coordinates, and capital cities
- 🏙️ **City Search**: Find cities by name, country, or population range
- 📍 **Proximity Search**: Find nearby cities based on IP geolocation
- 📊 **Wikipedia Integration**: Automatically enriches data with information from Wikidata
- 🗄️ **MongoDB Database**: Efficient data storage with geospatial indexing
- ⚡ **Built with Bun**: Fast runtime and package management
## Tech Stack
- **Runtime**: [Bun](https://bun.sh)
- **Framework**: Express.js
- **Database**: MongoDB with Mongoose
- **Language**: TypeScript
## API Endpoints
### Health Check
```
GET /health
```
Returns the health status of the API.
**Response:**
```json
{
"ok": true
}
```
### Countries
#### Get All Countries
```
GET /countries
```
Returns a list of all countries in the database.
**Response:**
```json
[
{
"CountryLabel": "spain",
"country": "Spain",
"CapitalLabel": "Madrid",
"iso2": "ES",
"population": 47450795,
"lifeExpectancy": 83.2,
"continent": "Europe",
"lat": 40.4,
"lon": -3.7,
}
]
```
#### Get Country by Name
```
POST /country
```
Get information about a specific country.
**Request Body:**
```json
{
"country": "spain"
}
```
**Response:**
```json
[
{
"CountryLabel": "spain",
"country": "Spain",
"CapitalLabel": "Madrid",
"iso2": "ES",
"population": 47450795,
"lifeExpectancy": 83.2,
"continent": "Europe",
"lat": 40.4,
"lon": -3.7,
}
]
```
#### Update Countries from Wikipedia
```
GET /getIdWiki
```
Admin endpoint to update country data from Wikidata (life expectancy, wiki IDs, etc.).
### Cities
#### Get Cities Near You
```
GET /nearme
```
Returns the 5 closest cities to your current location based on your IP address.
**Response:**
```json
[
{
"city": "Madrid",
"cityLabel": "madrid",
"country": "507f1f77bcf86cd799439011",
"location": {
"type": "Point",
"coordinates": [-3.7038, 40.4168]
},
"population": 3223334
}
]
```
#### Search Cities
```
GET /getCity
```
Search for cities by name, country, and/or population range.
**Query Parameters:**
- `city` (string): City name (case-insensitive)
- `country` (string): Country name (case-insensitive)
- `minPopulation` (number): Minimum population
- `maxPopulation` (number): Maximum population
**Example:**
```
GET /getCity?city=madrid&country=spain
GET /getCity?minPopulation=1000000&maxPopulation=5000000
```
**Response:**
```json
[
{
"city": "Madrid",
"cityLabel": "madrid",
"country": "507f1f77bcf86cd799439011",
"location": {
"type": "Point",
"coordinates": [-3.7038, 40.4168]
},
"population": 3223334
}
]
```
## Installation
### Prerequisites
- [Bun](https://bun.sh) installed
- MongoDB instance running
- Redis instance running (optional, for ratelimit)
### Setup
1. Clone the repository:
```bash
git clone https://github.com/txuli/finda.city.git
cd finda.city
```
2. Install dependencies:
```bash
bun install
```
3. Configure environment variables (create a `.env` file):
```env
PORT=3000
MONGODB_URI=mongodb://localhost:27017/finda
REDIS_URL=redis://localhost:6379
```
4. Start the server:
```bash
bun run src/index.ts
```
The API will be running at `http://localhost:3000`
## Data Models
### Country Schema
```typescript
{
CountryLabel: string, // Lowercase country name
country: string, // Capitalized country name
CapitalLabel: string, // Capital city name
iso2: string, // ISO 3166-1 alpha-2 code
population: number, // Country population
lifeExpectancy: number, // Life expectancy in years
continent: string, // Continent name
lat: number, // Latitude
lon: number, // Longitude
fullData: boolean, // Data completeness flag
wikiId: string // Wikidata ID (e.g., "Q29")
}
```
### City Schema
```typescript
{
city: string, // City name
cityLabel: string, // Lowercase city name
country: ObjectId, // Reference to Country
location: {
type: "Point",
coordinates: [number, number] // [longitude, latitude]
},
population: number // City population
}
```