High-Performance Indonesian Prayer Time Engine & API (REST & gRPC)
Jadwal waktu shalat presisi khusus wilayah Indonesia ๐ฎ๐ฉ selaras dengan data hisab resmi Bimas Islam Kementerian Agama RI.
๐ Web Demo โข ๐ Skenario โข ๐พ Data Source โข ๐ Cara Menjalankan โข ๐ก Endpoint API
ADZAN merupakan REST & gRPC API yang menyediakan jadwal waktu shalat presisi khusus untuk seluruh wilayah ๐ฎ๐ฉ Indonesia.
Berbeda dari API waktu shalat pada umumnya yang menghitung posisi matahari secara real-time menggunakan rumus hisab/algoritma astronomi kompleks, ADZAN menggunakan metode berbasis data tabel (lookup table berulang/perpetual) yang disadur langsung dari jadwal hisab resmi Bimas Islam Kementerian Agama Republik Indonesia.
Sebagian besar API jadwal shalat mengandalkan kalkulasi trigonometri/astronomi saat request datang (on-the-fly). Pendekatan tersebut membutuhkan beban CPU lebih tinggi dan sering kali menghasilkan selisih 1โ3 menit dari jadwal resmi yang digunakan oleh masjid-masjid di Indonesia.
Di wilayah tropis seperti Indonesia, variasi siklus waktu shalat pada tanggal dan bulan yang sama antar-tahun sangat kecil (rentang perbedaannya dapat diabaikan). Dengan menyimpan jadwal 366 hari per kota dalam bentuk data tabel:
-
Performa Tinggi & Latensi Sangat Rendah: Query beroperasi dalam kompleksitas
$O(1)$ langsung dari memory cache atau file CSV lokal tanpa kalkulasi rumit. - Hemat Sumber Daya: Sangat ringan dan efisien, cocok di-deploy pada server berspesifikasi kecil, micro-instance, hingga single-board computer (SBC).
- Konsisten: Waktu shalat yang disajikan selaras dengan acuan Kementerian Agama RI yang berlaku di masyarakat.
ADZAN dirancang fleksibel untuk dijadikan penyedia data (backend provider) berbagai integrasi:
- ๐ Website & Portal: Menampilkan widget jadwal shalat harian atau tabel bulanan di portal berita, blog, atau web instansi.
- ๐ฑ Aplikasi Mobile: Sumber data backend untuk aplikasi Android / iOS, lock screen notification, dan aplikasi pengingat ibadah.
- ๐ฅ๏ธ Desktop & Smartphone Widgets: Widget layar utama smartphone atau sistem operasi desktop.
- ๐ Perangkat Jadwal Shalat Masjid: Digunakan oleh display jam digital masjid, display running text LED, Smart TV masjid, hingga perangkat otomasi audio adzan berbasis mini-PC / Raspberry Pi / ESP32.
ADZAN mendukung dua pilihan arsitektur penyimpanan data yang dapat diatur melalui konfigurasi:
- CSV (Standalone / File-Based):
- Data dibaca dari file CSV per kota (
data/praytimes/{city_code}.csv) dan daftar kota (data/cities.csv). - Dilengkapi in-memory cache dan lazy loading otomatis.
- Tanpa dependensi luar: Aplikasi dapat langsung berjalan mandiri tanpa memerlukan server database/Redis.
- Data dibaca dari file CSV per kota (
- Redis (In-Memory Key-Value):
- Data disimpan dalam Redis Hash berulang bulanan (
praytime:{city_code}:{MM}). - Cocok untuk deployment skala besar atau arsitektur microservices terdistribusi.
- Data disimpan dalam Redis Hash berulang bulanan (
Pastikan sistem Anda telah terpasang Go (versi 1.16+).
-
Clone repositori:
git clone https://github.com/kaharman/adzan.git cd adzan -
Siapkan file konfigurasi: Salin template konfigurasi bawaan:
cp config.yaml.example config.yaml
Buka
config.yamldan sesuaikan pengaturan sepertidata_source(csvatauredis),port, sertaserver.base_pathjika memerlukan prefix URL. -
Jalankan aplikasi:
# Menjalankan langsung via Go go run app/main.go # Atau compile binary terlebih dahulu go build -o adzan-service app/main.go ./adzan-service
Aplikasi akan mulai berjalan pada port yang ditentukan (default
4321).
Docker image resmi otomatis di-build multi-arsitektur (linux/amd64 dan linux/arm64) dan dipublikasikan ke GitHub Container Registry (GHCR).
-
Pull image terbaru:
docker pull ghcr.io/kaharman/adzan:latest
-
Jalankan kontainer (Mode CSV bawaan):
docker run -d --name adzan-service \ -p 4321:4321 \ ghcr.io/kaharman/adzan:latest
-
Jalankan kontainer dengan volume mount data kustom:
docker run -d --name adzan-service \ -p 4321:4321 \ -v $(pwd)/data:/data \ -e DATA_SOURCE=csv \ -e CSV_PATH=/data \ ghcr.io/kaharman/adzan:latest -
Jalankan kontainer dengan data source Redis:
docker run -d --name adzan-service \ -p 4321:4321 \ -e DATA_SOURCE=redis \ -e REDIS_HOST=host.docker.internal \ -e REDIS_PORT=6379 \ ghcr.io/kaharman/adzan:latest
Dokumentasi OpenAPI / Swagger UI interaktif tersedia langsung di:
http://localhost:4321/openapi/
(Atau http://localhost:4321{base_path}/openapi/ jika menggunakan server.base_path)
-
Jadwal Hari Ini (Kota Jakarta):
curl -s "http://localhost:4321/today?city_code=3171" -
Jadwal Tanggal Spesifik:
curl -s "http://localhost:4321/daily?city_code=3171&date=2026-11-02" -
Jadwal 1 Bulan Penuh:
curl -s "http://localhost:4321/monthly?city_code=3171&month=11&year=2026" -
Jadwal 1 Tahun:
curl -s "http://localhost:4321/yearly?city_code=3171&year=2026" -
Pencarian Kota:
curl -s "http://localhost:4321/city/search?city=bandung" -
Detail Kota berdasarkan Kode / Koordinat:
curl -s "http://localhost:4321/city?city_code=3171" curl -s "http://localhost:4321/city?latitude=-6.170089&longitude=106.831050"
Tersedia antarmuka web modern dengan jam analog presisi, hitung mundur menuju waktu shalat berikutnya, kalender Hijriah, pratinjau jadwal imsakiyah, dan live core API explorer:
- Live Web App: https://adzan.kaharman.my.id
Data waktu shalat yang disajikan dalam API ini dihimpun dan disesuaikan langsung dari data publik Bimas Islam Kementerian Agama Republik Indonesia. Penyusun/pengembang berusaha menjaga keakuratan pemrosesan data, namun tidak bertanggung jawab atas potensi ketidaksesuaian atau kesalahan data yang bersumber langsung dari data primer penyedia aslinya. Pengguna disarankan untuk tetap melakukan kroscek dengan otoritas setempat bila diperlukan.
Proyek ini dilisensikan di bawah MIT License.