README.md

metadata

title: Bogor Xplore API
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: Flask API for Bogor tourism recommendations

BogorXplore Flask API

Flask API untuk data wisata, pencarian semantik, dan rekomendasi destinasi BogorXplore. API ini dipakai oleh aplikasi Laravel di ../web_recommendation.

Ringkasan

• Local development port: 5000.
• Docker/Hugging Face Space port: 7860.
• Dataset mentah dan response API: 296 destinasi dari data/bogor_tourism_data.csv.
• Search memakai IndoBERT similarity/query embedding.
• Rekomendasi detail wisata memakai precomputed N-Gram + TF-IDF similarity.

Quick Start Lokal

Dari root repo:

cd flask_api
pip install -r requirements.txt
python app.py

API berjalan di:

http://localhost:5000

Catatan: startup pertama dapat lebih lama karena model IndoBERT indobenchmark/indobert-base-p1 dimuat oleh Transformers.

Endpoint

Method	Endpoint	Fungsi
GET	/	Health check dan daftar endpoint utama.
GET	/api/places	Daftar destinasi dengan pagination dan filter kategori.
GET	/api/places/id	Detail destinasi berdasarkan index internal API, contoh /api/places/1.
GET	/api/search?q=query	Pencarian semantik berbasis IndoBERT.
POST	/api/recommendations	Rekomendasi destinasi berdasarkan place_name atau place_id.

Contoh Request

Health check:

curl http://localhost:5000/

Daftar destinasi:

curl "http://localhost:5000/api/places?limit=20&offset=0&category=Alam"

Pencarian semantik:

curl "http://localhost:5000/api/search?q=air%20terjun&limit=10"

Rekomendasi:

curl -X POST "http://localhost:5000/api/recommendations" `
  -H "Content-Type: application/json" `
  -d "{\"place_name\":\"Curug Ciampea\",\"top_n\":5}"

Payload rekomendasi:

{
  "place_name": "Curug Ciampea",
  "top_n": 5
}

place_name lebih aman dipakai dari Laravel karena place_id adalah index internal data API, bukan primary key database MySQL Laravel.

Struktur

flask_api/
├── api/                    # ruang tambahan untuk modul API jika diperlukan
├── data/                   # dataset dan artefak ML precomputed
├── models/
│   ├── __init__.py
│   ├── preprocessor.py
│   └── recommender.py
├── .dockerignore
├── .gitattributes
├── .python-version
├── app.py
├── Dockerfile
├── README.md
├── reproduce_error.py
├── requirements.txt
├── test_api.py
└── test_search.py

File Data Penting

File	Fungsi
data/bogor_tourism_data.csv	Dataset clean mentah, 296 destinasi.
data/bogor_tourism_data.json	Dataset clean dalam format JSON.
data/data_preprocessed.csv	Data hasil preprocessing notebook.
data/data_with_keywords.csv	Data dengan unigram, bigram, dan trigram; dipakai recommender.
data/tfidf_matrix.npy	Matrix TF-IDF.
data/tfidf_vectorizer.pkl	Vectorizer TF-IDF untuk query/search.
data/ngram_similarity.npy	Similarity N-Gram precomputed.
data/indobert_embeddings.npy	Embedding IndoBERT.
data/indobert_similarity.npy	Similarity IndoBERT precomputed.
data/combined_similarity.npy	Artefak similarity gabungan dari notebook.

Model Rekomendasi

Pipeline ML utama dikembangkan di ../dataset:

Data clean
-> preprocessing
-> N-Gram + TF-IDF
-> IndoBERT embedding
-> cosine similarity per metode
-> search IndoBERT dan rekomendasi detail N-Gram + TF-IDF

Implementasi API saat ini:

• /api/search memakai IndoBERT. Jika query sama persis dengan nama tempat, API memakai indobert_similarity.npy; jika tidak, query di-encode langsung.
• /api/recommendations mencari tempat dari place_name terlebih dahulu, lalu mengambil rekomendasi detail wisata dari ngram_similarity.npy (N-Gram + TF-IDF).

Sinkronisasi Artefak

Jika notebook di ../dataset menghasilkan artefak baru, salin file yang dibutuhkan ke flask_api/data sebelum menjalankan API atau deploy ulang.

File yang biasanya disinkronkan:

data_preprocessed.csv
data_with_keywords.csv
tfidf_matrix.npy
tfidf_vectorizer.pkl
ngram_similarity.npy
indobert_embeddings.npy
indobert_similarity.npy
tabel_perbandingan.csv
tabel_akurasi_kategori.csv

Docker dan Hugging Face Space

Build lokal dari folder flask_api:

docker build -t bogor-xplore-api .
docker run --rm -p 7860:7860 bogor-xplore-api

Docker menjalankan:

gunicorn --bind 0.0.0.0:7860 --timeout 300 app:app

File .github/workflows/sync-flask-api-to-hf.yml melakukan sync folder flask_api/ ke Hugging Face Space saat ada push ke branch main yang mengubah folder ini atau workflow tersebut. Workflow membutuhkan secret HF_TOKEN.

Test Manual

Jalankan API dulu, lalu:

python test_api.py
python test_search.py

test_api.py memanggil endpoint rekomendasi, sedangkan test_search.py memanggil endpoint pencarian semantik.

Dependencies

Daftar lengkap ada di requirements.txt.

Paket utama:

• Flask
• Flask-CORS
• Pandas
• NumPy
• scikit-learn
• Transformers
• PyTorch
• Sastrawi
• Gunicorn

Troubleshooting

Masalah	Solusi
API lama saat startup	Tunggu model IndoBERT selesai dimuat.
ModuleNotFoundError	Jalankan pip install -r requirements.txt.
File .npy atau .pkl tidak ditemukan	Sinkronkan artefak dari ../dataset/data ke flask_api/data.
Rekomendasi tidak sesuai tempat Laravel	Kirim place_name selain place_id dari Laravel.
Deploy Hugging Face gagal	Pastikan HF_TOKEN ada dan Git LFS asset flask_api/data/** ikut ter-pull.

Lisensi

Educational Project - BogorXplore.