Skip to content
BranchesTags

Repository files navigation

🗺️ SimpleMaps

Navigasi Rute Cerdas Multi-Moda & Estimasi BBM

Aplikasi navigasi dan kalkulasi rute berbasis PHP yang membandingkan rute tercepat vs paling hemat bahan bakar, mendukung moda Mobil, Motor, dan Jalan Kaki, dengan opsi jalan tikus (alley), filter tanjakan curam, serta analisis kemacetan berbasis waktu.

Fitur • Arsitektur • Instalasi • Dokumentasi API • Struktur Proyek • Testing

✨ Fitur

  • 🚗 Multi-Moda Transportasi — Perhitungan rute khusus untuk car, motorcycle, dan foot dengan kalibrasi kecepatan & konsumsi masing-masing moda.
  • ⚡ Perbandingan Rute Cerdas — Selalu menghasilkan 3 alternatif: Rute Tercepat, Rute Paling Hemat BBM, dan Rute Alternatif Jalan Tikus, lengkap dengan ringkasan selisih waktu & penghematan Rupiah.
  • 🛣️ Preferensi Jalan Tikus (Alley) — Opsi avoid (hindari), allow (izinkan), dan prefer (prioritaskan gang/jalan sempit untuk memotong jarak).
  • ⛰️ Profil Elevasi & Tanjakan Curam — Analisis total tanjakan (ascent), turunan (descent), deteksi kemiringan ≥ 8%, plus filter avoid_steep_slopes untuk jalur yang lebih landai.
  • ⛽ Estimasi Konsumsi & Biaya BBM — Model perhitungan multi-faktor (jarak, elevasi, stop-and-go, kemacetan) dengan harga BBM Rupiah (Pertalite, Pertamax, Solar) dan dukungan fuel rate kustom.
  • 🚦 Analisis Kemacetan Berbasis Waktu — Pemodelan jam sibuk (morning_rush, evening_rush, off_peak) yang menyesuaikan durasi tempuh dan penalti idling bahan bakar per moda.
  • 🧭 Navigasi Turn-by-Turn — Instruksi belokan detail dalam Bahasa Indonesia ("Belok kiri ke Jl. Sudirman sejauh 300 m").
  • 🔍 Geocoding Autocomplete — Pencarian alamat/tempat via OpenStreetMap Nominatim (prioritas Indonesia) dengan fallback landmark populer offline.
  • 🗄️ Arsitektur Hybrid Berlapis — OSRM publik (default, tanpa API key) → OpenRouteService (opsional) → Simulator internal offline.

🧱 Arsitektur

SimpleMaps menggunakan strategi hybrid berlapis 3-tier untuk menjamin rute selalu tersedia (ADR-0002):

┌────────────────────────────────────────────────────────────────┐
│                        Frontend (index.html)                    │
│       Leaflet Map • Tailwind CSS • Chart.js (Elevation)        │
└──────────────────────────────┬─────────────────────────────────┘
                               │ REST JSON
┌──────────────────────────────▼─────────────────────────────────┐
│                      PHP Router (public/index.php)             │
│        /api/geocoding/search      /api/routes/calculate        │
└──────────────────────────────┬─────────────────────────────────┘
                               │
┌──────────────────────────────▼─────────────────────────────────┐
│                      RoutingService (Hybrid)                    │
│                                                                │
│  Tier 1: OpenRouteService (jika OPENROUTESERVICE_API_KEY ada)  │
│  Tier 2: OSRM Public API (default, gratis, tanpa token) ◄───── Default │
│  Tier 3: RoutingSimulator (fallback offline)                   │
│                                                                │
│  ├── ElevationService  ──→  profil tanjakan/turunan            │
│  ├── FuelCalculationService ──→  estimasi liter & biaya (Rp)   │
│  └── TrafficService   ──→  model kemacetan berbasis waktu      │
└────────────────────────────────────────────────────────────────┘

Cara kerja fallback chain: Jika provider prioritas gagal (timeout, error, atau tidak ada API key), sistem otomatis turun ke provider berikutnya sehingga kalkulasi rute tidak pernah terputus.

Tech Stack

Komponen Teknologi
Backend PHP ≥ 7.4 (native, tanpa framework)
Routing OSRM Public API • OpenRouteService API
Geocoding OpenStreetMap Nominatim
Frontend Tailwind CSS • Leaflet.js • Chart.js • Font Awesome
Testing PHPUnit 9.5 / 10

📦 Persyaratan

  • PHP ≥ 7.4 (dengan ekstensi curl dan json)
  • Composer (hanya untuk menjalankan test PHPUnit)
  • Koneksi internet (untuk OSRM / Nominatim; mode simulasi tetap berjalan offline)

🚀 Instalasi

1. Clone & Install Dependensi

git clone https://github.com/username/simplemaps.git
cd simplemaps

# Install dependensi dev (PHPUnit) — opsional jika hanya menjalankan aplikasi
composer install

2. Konfigurasi Environment

cp .env.example .env

Buka .env dan sesuaikan sesuai kebutuhan:

APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost/simplemaps

# Isi jika ingin memakai OpenRouteService (opsional — biarkan kosong untuk memakai OSRM gratis)
OPENROUTESERVICE_API_KEY=

# Efisiensi kendaraan default (km/liter)
DEFAULT_CAR_FUEL_RATE=12.0
DEFAULT_MOTORCYCLE_FUEL_RATE=45.0

# Harga BBM default (Rp/liter)
FUEL_PRICE_PERTALITE=10000
FUEL_PRICE_PERTAMAX=12950
FUEL_PRICE_SOLAR=6800

3. Jalankan Aplikasi

Opsi A — PHP Built-in Server (cara tercepat)

cd public
php -S localhost:8000

Buka http://localhost:8000 di browser.

Opsi B — Laragon / XAMPP / Apache

Letakkan project di www/ (Laragon) atau htdocs/ (XAMPP), lalu buka http://localhost/simplemaps. Rewrite .htaccess sudah disertakan di public/.

Catatan virtual host: pastikan DocumentRoot mengarah ke folder public/ agar routing API bekerja dengan benar.

🔌 Dokumentasi API

Endpoint

Metode Endpoint Deskripsi
GET /api/health Status kesehatan aplikasi
GET /api/geocoding/search?q=... Pencarian alamat / autocomplete
POST /api/routes/calculate Kalkulasi rute & estimasi BBM

Contoh Request — Kalkulasi Rute

curl -X POST http://localhost:8000/api/routes/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "latitude": -6.200000, "longitude": 106.816666 },
    "destination": { "latitude": -6.175392, "longitude": 106.827153 },
    "waypoints": [],
    "mode": "motorcycle",
    "alley_preference": "prefer",
    "avoid_steep_slopes": true,
    "departure_time": "evening_rush",
    "fuel_type": "pertalite",
    "fuel_price": 10000,
    "base_fuel_rate": 45
  }'

Parameter Request

Parameter Tipe Default Deskripsi
origin object wajib { latitude, longitude }
destination object wajib { latitude, longitude }
waypoints array [] Titik perantara opsional
mode string car car • motorcycle • foot
alley_preference string avoid avoid • allow • prefer
avoid_steep_slopes boolean false Hindari tanjakan curam (≥ 8%)
departure_time string now now • morning_rush • evening_rush • off_peak • midday • "HH:MM"
fuel_type string pertalite pertalite • pertamax • solar
fuel_price number default konfig Harga per liter (Rp), null = pakai default
base_fuel_rate number default moda Efisiensi kendaraan (km/L), null = pakai default

Contoh Response (ringkas)

{
  "message": "Kalkulasi rute berhasil diselesaikan",
  "data": {
    "mode": "motorcycle",
    "routes_count": 3,
    "routes": [
      {
        "id": "osrm_0_...",
        "type": "fastest",
        "title": "Rute Tercepat (Jalan Utama)",
        "distance_meters": 8420.5,
        "duration_seconds": 798,
        "traffic": { "traffic_level": "Macet Padat", "delay_formatted": "+12 mnt" },
        "elevation_profile": { "total_ascent_m": 42, "steep_slopes_count": 1 },
        "fuel_calculation": {
          "total_liters": 0.41,
          "total_cost_idr": 4100,
          "base_fuel_rate": 45.0
        },
        "steps": [
          { "instruction": "Belok kiri ke Jl. Sudirman", "distance_m": 300, "duration_s": 28 }
        ]
      }
    ],
    "comparison": {
      "recommended_route_id": "osrm_0_...",
      "fuel_savings_liters": 0.12,
      "fuel_savings_idr": 1200,
      "fuel_savings_formatted": "Rp 1.200",
      "extra_time_minutes": 4.5
    }
  }
}

🗂️ Struktur Proyek

simplemaps/
├── public/                    # Web root
│   ├── index.php              # Entry point & router API
│   ├── index.html             # Frontend (Leaflet + Tailwind + Chart.js)
│   └── .htaccess              # Rewrite rules (Apache)
├── src/
│   ├── Controllers/
│   │   ├── RouteCalculationController.php
│   │   └── GeocodingController.php
│   ├── Services/              # Logika bisnis
│   │   ├── RoutingService.php         # Orchestrator hybrid 3-tier
│   │   ├── RoutingSimulator.php       # Fallback offline
│   │   ├── FuelCalculationService.php # Model konsumsi BBM
│   │   ├── ElevationService.php       # Profil elevasi
│   │   ├── TrafficService.php         # Model kemacetan
│   │   └── GeocodingService.php       # Nominatim + fallback
│   ├── Models/
│   │   ├── Coordinates.php
│   │   ├── RouteAlternative.php
│   │   ├── RouteStep.php
│   │   ├── Maneuver.php
│   │   ├── ElevationProfile.php
│   │   └── FuelCalculationResult.php
│   └── Utils/
│       ├── Router.php         # Micro HTTP router
│       ├── Response.php       # JSON response helper
│       ├── Env.php            # .env loader
│       └── GeoMath.php        # Perhitungan spasial
├── config/config.php          # Konfigurasi global
├── tests/                     # Unit & Integration tests
├── docs/
│   ├── adr/                   # Architecture Decision Records
│   └── agents/                # Panduan untuk AI agents
├── .env.example
├── composer.json
└── CONTEXT.md                 # Glosarium domain

🧪 Testing

# Opsi 1 — PHPUnit (perlu composer install)
vendor/bin/phpunit

# Opsi 2 — Test runner mandiri tanpa dependensi
APP_ENV=testing php tests/run_tests.php

Test mencakup validasi koordinat, profil elevasi, model konsumsi BBM, analisis kemacetan, simulator routing, dan integrasi kalkulasi rute.

🛣️ Roadmap

  • Routing Cache Layer — cache respons OSRM/ORS (Redis/SQLite) untuk rute populer (ADR-0002)
  • Self-Hosted OSRM — instance Docker OSRM lokal dengan PBF Indonesia
  • Filter Jalan Tol (Tollways) — saklar rute non-tol di antarmuka web
  • Data Elevasi SRTM — elevasi satelit riil via OpenRouteService

📚 Referensi

📄 Lisensi

Distributed under the MIT License.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages