🌍 Xenohuru API

REST API for Tanzania tourism — GPS-accurate attractions, real-time weather, and open data for developers.

Live API: https://xenohuru.cleven.is-a.dev/ | Frontend UI: https://x.xenohuru.workers.dev/ | Sponsor Us: Ko-fi

---

About

Open-source Tanzania tourism API by Xenohuru — From Greek "xenos" (explorer) + Swahili "huru" (free).

This backend provides GPS-accurate attraction data, real-time weather, and REST API for developers building tourism experiences.

---

Architecture

xenohuru-api/
├── src/
│   ├── app/
│   │   ├── accounts/     # User authentication & JWT
│   │   ├── attractions/  # Attractions API
│   │   ├── regions/      # Regions API
│   │   └── weather/      # Weather integration
│   ├── config/           # Application settings
│   └── manage.py
├── requirements.txt
└── docs/

Features:

• RESTful API design
• JWT authentication
• Real-time weather (Open-Meteo)
• GPS-accurate locations
• OpenAPI documentation
• Pagination support

---

Quick Start

Prerequisites

• Python 3.10+, pip, virtualenv
• PostgreSQL (recommended for production) or SQLite (dev only)

Installation

git clone https://github.com/Xenohuru/xenohuru-api.git
cd xenohuru-api
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env  # Edit with your config
python manage.py migrate
python manage.py runserver

API runs at: http://localhost:8000/api/ | Admin: http://localhost:8000/admin/

PostgreSQL configuration (native env vars)

Set these environment variables (see .env.example):

• DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, DB_PORT
• DB_SSLMODE (default: require)

When DB_HOST is set, the API uses PostgreSQL as the database backend.

Migrating from SQLCipher SQLite (chui.db) to PostgreSQL

1. On the current server (SQLite/SQLCipher) export data:

If your chui.db is SQLCipher-encrypted, install the optional dependency first:

pip install sqlcipher3

Then export:

export USE_SQLCIPHER=true
export DB_ENCRYPTION_KEY='your-key'
unset DB_HOST DB_NAME DB_USER DB_PASSWORD DB_PORT
python manage.py dumpdata --natural-foreign --natural-primary \
  --exclude contenttypes --exclude auth.permission --indent 2 > data.json

2. Point the app to PostgreSQL (set DB_*), run migrations, then import:

python manage.py migrate
python manage.py loaddata data.json

If you hit sequence/ID issues on Postgres after loaddata, run a sequence reset (per-app):

python manage.py sqlsequencereset appname1 appname2 | \
  PGPASSWORD="$DB_PASSWORD" psql -h "$DB_HOST" -U "$DB_USER" -d "$DB_NAME"

---

API Endpoints

Endpoint	Method	Description
/attractions/	GET	List attractions
/attractions/:slug/	GET	Attraction details
/regions/	GET	List regions
/weather/	GET	Current weather (by coordinates or attraction)
/auth/login/	POST	User authentication
/auth/register/	POST	User registration

Full docs: https://xenohuru.cleven.is-a.dev/ (Swagger)

---

Testing

python manage.py test  # Run all tests
python manage.py test app.attractions  # Run specific app

---

Tech Stack

• Language: Python 3.10+
• Database: PostgreSQL
• Auth: JWT (JSON Web Tokens)
• Weather: Open-Meteo API
• Docs: OpenAPI 3.0 (Swagger UI)
• Cloud Storage: Cloudinary

---

Key Features

For API Consumers:

• RESTful design with predictable endpoints
• Comprehensive OpenAPI documentation
• JWT authentication support
• Fast response times with database optimization
• Pagination & filtering support
• Free & open-source

For Developers:

• Well-tested codebase
• Clear code structure & documentation
• Modular architecture - easy to extend
• Docker support (coming soon)
• CI/CD with GitHub Actions

---

Contributing

We welcome contributors! Fork the repo, create a branch, and submit a PR.

Steps:

1. Fork the repository
2. Create feature branch: git checkout -b feature/your-feature
3. Make changes & test
4. Commit: git commit -m "Add feature"
5. Push & open PR

Read: CONTRIBUTING.md | CODE_OF_CONDUCT.md

---

License

MIT License — see LICENSE

---

🌍 REST API for Tanzania Tourism | 🇹🇿 From Tanzania | ❤️ Support us on Ko-fi