turkiye-api-py 1.1.1

Comprehensive REST API and Python SDK for Turkey's administrative divisions with demographic and geographical data

Turkiye API (Python/FastAPI)

Language / Dil: English | Türkçe

Version 1.1.1 | Production Ready ✅

TurkiyeAPI is a comprehensive REST API providing detailed information about Turkey's administrative divisions including provinces, districts, neighborhoods and villages with demographic and geographical data.

This is a Python/FastAPI implementation based on the original turkiye-api project by Ubeyde Emir Özdemir, licensed under the MIT License.

✨ Features

Core Features

• FastAPI Framework: Modern, fast (high-performance), web framework for building APIs
• Multi-Language Documentation: Automatic language detection with English and Turkish support
• Scalar Documentation: Beautiful, interactive API documentation with modern UI
• OpenAPI Support: Full OpenAPI 3.0 specification in multiple languages
• Type Safety: Full type hints with Pydantic models
• API Versioning: Comprehensive versioning strategy (/api/v1/...) for smooth migrations

Security & Performance 🔒⚡

• OWASP Security Headers: All critical security headers implemented (CSP, X-Frame-Options, HSTS, etc.)
• Secured Health Endpoint: Environment-aware detail levels with optional authentication
• Redis Caching: High-performance distributed caching with automatic key generation and 30-minute TTL
• Rate Limiting: Built-in rate limiting with Redis support for distributed deployments
• CORS Configuration: Environment-aware Cross-Origin Resource Sharing
• GZip Compression: Automatic response compression for better performance

Quality & DevOps 🧪🚀

• Comprehensive Testing: 80+ tests across all layers (data, services, API, middleware)
• Automated Workflows: GitHub Actions for data and documentation synchronization
• Pre-commit Hooks: Automated code quality checks (Black, isort, flake8, Bandit, mypy)
• Code Quality: 9.0/10 quality score with excellent maintainability
• Production Ready: Docker, Gunicorn, comprehensive deployment guides, and production config templates

Monitoring & Observability 📊

• Prometheus Metrics: Built-in metrics at /metrics endpoint
• Structured Logging: JSON logging with configurable levels
• Health Checks: Enhanced health endpoint with dependency status monitoring

Requirements

• Python 3.8+
• pip

Installation

1. Clone the repository:

git clone https://github.com/gencharitaci/turkiye-api-py.git
cd turkiye-api-py

2. Create a virtual environment:

python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Create a .env file:

# For development
cp .env.example .env

# For production (recommended)
cp .env.production.recommended .env

Edit .env to customize settings. See Configuration section for details.

5. (Optional) Set up pre-commit hooks for code quality:

pip install pre-commit
pre-commit install

Using as Python SDK

After installing via pip, you can use the package as a Python SDK to interact with any Turkiye API server:

Installation from PyPI

# Install the latest version
pip install turkiye-api-py

# Or install a specific version
pip install turkiye-api-py==1.1.1

Quick Start with SDK

from app import TurkiyeClient

# Connect to a running API server (you need to have a server running)
client = TurkiyeClient(base_url="http://localhost:8181")

# Get all provinces
provinces = client.get_provinces()
print(f"Total provinces: {len(provinces)}")

# Get Istanbul (ID: 34)
istanbul = client.get_province(34)
print(f"{istanbul['name']}: {istanbul['population']:,} people")

# Get districts in Istanbul
districts = client.get_districts(province_id=34)
print(f"Istanbul has {len(districts)} districts")

# Filter provinces by population
large_cities = client.get_provinces(min_population=1000000)
for city in large_cities:
    print(f"{city['name']}: {city['population']:,}")

Running Your Own API Server

To use the SDK, you need an API server running. You can either:

Option 1: Run the server from the installed package

# Start the server (after pip install)
turkiye-api serve

# Start with auto-reload for development
turkiye-api serve --reload

# Start on a custom port
turkiye-api serve --port 8000

Option 2: Connect to an existing server

from app import TurkiyeClient

# Connect to a remote server
client = TurkiyeClient(base_url="https://your-api-domain.com")
provinces = client.get_provinces()

SDK Features

• Simple & Pythonic: Clean, intuitive API
• Type Hints: Full type annotations for better IDE support
• Error Handling: Comprehensive error messages
• Context Manager: Automatic resource cleanup
• Pagination: Built-in pagination support
• Filtering: Advanced filtering options
• Language Support: English and Turkish responses

For complete SDK documentation and examples, see SDK_USAGE.md

Running the Application

Development Mode

python run.py

The API will be available at: http://localhost:8181

Production Mode

For production deployment, we recommend using Gunicorn with Uvicorn workers or Docker:

Option 1: Docker (Recommended)

docker-compose up -d

Option 2: Gunicorn

gunicorn -c gunicorn.conf.py app.main:app

Option 3: Quick Start Scripts

# Linux/Mac
chmod +x start-production.sh
./start-production.sh

# Windows
start-production.bat

For detailed production deployment instructions, see DEPLOYMENT_EN.md or DEPLOYMENT_TR.md

Configuration

Environment Variables

Key configuration options (see .env.production.recommended for complete list):

# Application
ENVIRONMENT=production
DEBUG=false
PORT=8181
WORKERS=4

# Security (CRITICAL for production)
EXPOSE_SERVER_HEADER=false
HEALTH_CHECK_DETAILED=false
HEALTH_CHECK_AUTH_ENABLED=true
HEALTH_CHECK_PASSWORD=your-secure-password

# Redis (for caching and rate limiting)
REDIS_URL=redis://localhost:6379/0

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=100

# CORS
ALLOWED_ORIGINS=https://yourdomain.com

Security Configuration

Production Security Checklist:

• ✅ Set HEALTH_CHECK_DETAILED=false to minimize information disclosure
• ✅ Enable HEALTH_CHECK_AUTH_ENABLED=true for sensitive environments
• ✅ Set strong HEALTH_CHECK_PASSWORD
• ✅ Keep EXPOSE_SERVER_HEADER=false to prevent technology stack exposure
• ✅ Configure ALLOWED_ORIGINS with your actual domains
• ✅ Enable HTTPS via reverse proxy (nginx/Apache)

All OWASP security headers are automatically applied:

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• X-XSS-Protection: 1; mode=block
• Content-Security-Policy (configured)
• Referrer-Policy: strict-origin-when-cross-origin
• Permissions-Policy (geolocation, microphone, camera disabled)
• Strict-Transport-Security (production only)

API Documentation

Once the server is running, you can access the documentation in multiple languages:

• Auto-Detect Language: http://localhost:8181/docs (Redirects based on browser language)
• English Documentation: http://localhost:8181/docs/en (Interactive Scalar UI)
• Turkish Documentation: http://localhost:8181/docs/tr (İnteraktif Scalar UI)
• English OpenAPI Spec: http://localhost:8181/openapi-en.json
• Turkish OpenAPI Spec: http://localhost:8181/openapi-tr.json

The documentation automatically detects your browser language and displays content in English or Turkish. You can also manually switch languages using the selector buttons in the top-right corner.

For more details, see the interactive documentation at /docs endpoint.

Documentation Guides

The guides/ folder contains comprehensive documentation synchronized from the turkiye-api-docs repository.

Auto-Sync: Documentation is automatically updated daily at 2:00 AM UTC via GitHub Actions.

Manual Sync:

# Linux/Mac
./scripts/sync-guides.sh

# Windows
scripts\sync-guides.bat

For detailed information about the sync mechanism, see GUIDES_SYNC.md

Data Synchronization

The app/data/ folder contains administrative data (provinces, districts, etc.) synchronized from the turkiye-api repository.

Auto-Sync: Data is automatically updated weekly on Sunday at 3:00 AM UTC via GitHub Actions.

Manual Sync:

# Linux/Mac
./scripts/sync-data.sh

# Windows
scripts\sync-data.bat

Features:

• ✅ Automatic JSON validation
• ✅ Backup before update
• ✅ Weekly scheduled sync
• ✅ Manual trigger available

For detailed information about data synchronization, see DATA_SYNC.md

Advanced Features

For information about advanced features including rate limiting, Redis integration, API versioning, and monitoring, see ADVANCED_FEATURES.md.

Quick Overview

• Rate Limiting: Protect your API from abuse with configurable rate limits
• Redis Integration: Distributed rate limiting for multi-instance deployments
• API Versioning: /api/v1/... with support for future versions
• Monitoring: Prometheus metrics at /metrics endpoint
• Version Info: Get supported versions at /api/versions

API Endpoints

System Endpoints

• GET /health - Enhanced health check with dependency status
• GET /api/versions - Get supported API versions information

Language Endpoints

• GET /api/v1/language - Get current language preference
• POST /api/v1/language - Set language preference
• GET /api/v1/languages - Get list of supported languages

Provinces

• GET /api/v1/provinces - Get all provinces with optional filters
• GET /api/v1/provinces/{id} - Get specific province by ID

Districts

• GET /api/v1/districts - Get all districts with optional filters
• GET /api/v1/districts/{id} - Get specific district by ID

Neighborhoods

• GET /api/v1/neighborhoods - Get all neighborhoods with optional filters
• GET /api/v1/neighborhoods/{id} - Get specific neighborhood by ID

Villages

• GET /api/v1/villages - Get all villages with optional filters
• GET /api/v1/villages/{id} - Get specific village by ID

Towns

• GET /api/v1/towns - Get all towns with optional filters
• GET /api/v1/towns/{id} - Get specific town by ID

Query Parameters

All list endpoints support these common query parameters:

• name: Filter by name (partial match)
• minPopulation: Minimum population filter
• maxPopulation: Maximum population filter
• offset: Pagination offset
• limit: Pagination limit
• fields: Comma-separated list of fields to return
• sort: Sort by field (prefix with - for descending)

Additional filters vary by endpoint. See the interactive documentation for details.

Example Requests

Get all provinces

curl http://localhost:8181/api/v1/provinces

Get provinces with population over 1 million

curl http://localhost:8181/api/v1/provinces?minPopulation=1000000

Get a specific province (Istanbul, id=34)

curl http://localhost:8181/api/v1/provinces/34

Get districts in a specific province

curl http://localhost:8181/api/v1/districts?provinceId=34

Get only specific fields

curl http://localhost:8181/api/v1/provinces?fields=id,name,population

Testing

The project includes comprehensive test coverage (80+ tests) across all layers.

Running Tests

# Install test dependencies
pip install pytest pytest-cov pytest-asyncio httpx

# Run all tests
pytest tests/ -v

# Run with coverage report
pytest tests/ -v --cov=app --cov-report=term-missing

# Run with HTML coverage report
pytest tests/ -v --cov=app --cov-report=html
# Open htmlcov/index.html in browser

Test Structure

tests/
├── test_data_loader.py              # DataLoader tests (14 tests)
├── test_api/
│   └── test_provinces_endpoint.py   # API integration tests (19 tests)
├── test_services/
│   ├── test_base_service.py         # Base service tests (18 tests)
│   └── test_province_service.py     # Province service tests (18 tests)
└── test_middleware/
    └── test_security.py             # Security middleware tests (11 tests)

Current Coverage: 80+ tests covering:

• ✅ Data loading and caching
• ✅ Service layer (filtering, sorting, pagination)
• ✅ API endpoints (all HTTP methods and error cases)
• ✅ Security middleware (all OWASP headers)

For detailed testing guide, see TESTING.md

Project Structure

turkiye-api-py/
├── app/
│   ├── data/                 # JSON data files
│   ├── i18n/                 # Internationalization
│   ├── middleware/           # Request/response middleware
│   │   ├── security.py       # Security headers (NEW)
│   │   ├── metrics.py        # Prometheus metrics
│   │   └── language.py       # Language detection
│   ├── models/               # Pydantic models and schemas
│   ├── routers/              # API route handlers
│   ├── services/             # Business logic layer
│   │   ├── cache_service.py  # Redis caching service (NEW)
│   │   ├── base_service.py   # Base service utilities
│   │   └── *_service.py      # Domain services
│   ├── main.py               # FastAPI application
│   ├── settings.py           # Configuration management
│   └── scalar_docs.py        # API documentation setup
├── tests/                    # Test suite (80+ tests) (NEW)
│   ├── test_api/             # API integration tests
│   ├── test_services/        # Service unit tests
│   ├── test_middleware/      # Middleware tests
│   └── conftest.py           # Test fixtures
├── docs/                     # Documentation (NEW)
│   ├── ADVANCED_FEATURES.md  # Advanced features guide
│   ├── CHANGELOG.md          # Version history
│   ├── DATA_SYNC.md          # Data synchronization guide
│   ├── DEPLOYMENT_EN.md      # Deployment guide (English)
│   ├── DEPLOYMENT_TR.md      # Deployment guide (Turkish)
│   ├── GUIDES_SYNC.md        # Documentation sync guide
│   ├── IMPLEMENTATION_SUMMARY.md  # Implementation details
│   ├── PRODUCTION_READINESS.md    # Production checklist
│   └── TESTING.md            # Testing guide
├── scripts/                  # Utility scripts (NEW)
│   ├── sync-data.sh          # Data sync script (Linux/Mac)
│   ├── sync-data.bat         # Data sync script (Windows)
│   ├── sync-guides.sh        # Guides sync script (Linux/Mac)
│   └── sync-guides.bat       # Guides sync script (Windows)
├── .github/
│   └── workflows/
│       ├── sync-data.yml     # Data sync workflow (NEW)
│       └── sync-guides.yml   # Guides sync workflow (NEW)
├── requirements.txt          # Python dependencies
├── run.py                    # Development server runner
├── gunicorn.conf.py          # Production Gunicorn configuration
├── Dockerfile                # Docker image definition
├── docker-compose.yml        # Docker Compose configuration
├── .env.example              # Development environment template
├── .env.production.recommended  # Production config template (NEW)
├── .pre-commit-config.yaml   # Pre-commit hooks (NEW)
├── README.md                 # This file (English)
└── README_TR.md              # Turkish README

Technology Stack

Core Framework

• FastAPI: Modern Python web framework
• Pydantic: Data validation using Python type annotations
• Uvicorn: ASGI server implementation
• Gunicorn: Production WSGI/ASGI server

Performance & Caching

• Redis: Distributed caching and rate limiting
• In-Memory Cache: Pre-indexed data structures for O(1) lookups

Security

• OWASP Headers: Comprehensive security header middleware
• CORS Middleware: Configurable cross-origin resource sharing
• Rate Limiting: Request throttling with Redis backend

Documentation & API

• Scalar: Beautiful, interactive API documentation UI
• OpenAPI 3.0: Full specification with multi-language support

Testing & Quality

• pytest: Testing framework with 80+ tests
• pytest-cov: Code coverage reporting
• pytest-asyncio: Async test support
• Black: Code formatting
• isort: Import sorting
• flake8: Linting
• Bandit: Security vulnerability scanning
• mypy: Static type checking

DevOps & Monitoring

• Docker: Containerization
• GitHub Actions: Automated data and documentation synchronization
• Prometheus: Metrics collection
• Pre-commit: Git hooks for code quality

Sources

• Population of districts
• Area of districts

Contributing

Contributions are welcome! This project maintains high quality standards with comprehensive testing and automated quality checks.

Development Workflow

1. Fork and Clone

   git clone https://github.com/YOUR_USERNAME/turkiye-api-py.git
   cd turkiye-api-py
   

2. Set Up Development Environment

   python -m venv venv
   source venv/bin/activate  # or venv\Scripts\activate on Windows
   pip install -r requirements.txt
   pip install pre-commit pytest pytest-cov
   pre-commit install
   

3. Create a Feature Branch

   git checkout -b feature/your-feature-name
   

4. Write Code and Tests

   • Follow existing code style (enforced by Black, isort, flake8)
   • Add tests for new features (maintain 80%+ coverage)
   • Update documentation as needed

5. Run Quality Checks

   # Run tests
   pytest tests/ -v --cov=app
   
   # Run pre-commit hooks
   pre-commit run --all-files
   

6. Commit and Push

   git add .
   git commit -m "feat: your feature description"
   git push origin feature/your-feature-name
   

7. Create Pull Request

   • Provide clear description of changes
   • Reference any related issues
   • Ensure all tests and quality checks pass locally

Coding Standards

• Code Style: Black formatting with 120-character line length
• Import Sorting: isort with Black profile
• Type Hints: Required for all public functions and methods
• Docstrings: Required for all public classes and functions
• Testing: Minimum 80% code coverage for new code
• Security: All code scanned by Bandit

Pull Request Guidelines

• ✅ All tests must pass
• ✅ Code coverage must not decrease
• ✅ Pre-commit hooks must pass
• ✅ Clear commit messages (conventional commits preferred)
• ✅ Update CHANGELOG.md for notable changes
• ✅ For major changes, open an issue first to discuss

Running Quality Checks Locally

Run these checks locally before committing to ensure code quality:

# Test matrix (Python 3.8-3.11)
pytest tests/ -v --cov=app

# Linting
black --check app/ tests/
isort --check app/ tests/
flake8 app/ tests/
mypy app/

# Security
bandit -r app/ -ll

Documentation

When adding new features:

• Update README.md (English and Turkish)
• Add examples to API documentation in app/scalar_docs.py
• Update DEPLOYMENT guides if configuration changes
• Add entries to CHANGELOG.md

Thank you for contributing to Turkiye API! 🎉

Credits

This project is based on the original turkiye-api by Ubeyde Emir Özdemir.

Original Author: Ubeyde Emir Özdemir

• Email: [e-mail]
• Telegram: @ubeydeozdmr
• GitHub: @ubeydeozdmr

Python Implementation: Adem Kurtipek

• Email: [e-mail]
• GitHub: @gencharitaci
• Repository: turkiye-api-py

License

This project is licensed under the MIT License - see the LICENSE file for details.

Based on the original turkiye-api project, also licensed under MIT.