VietFuelAPI

API giá xăng dầu Việt Nam thời gian thực — 11 Nguồn dữ liệu, 63 Tỉnh thành, Phân vùng 1 & 2 chuẩn xác.

English version: README.en.md

📖 Mục lục

• Giới thiệu
• Tính năng nổi bật
• Bắt đầu nhanh
• Danh sách Endpoint
• Phân vùng giá xăng dầu
• Công nghệ sử dụng
• Cấu trúc dự án
• Tài liệu chi tiết
• Pháp lý & Cộng đồng
• Giấy phép

👋 Giới thiệu

VietFuelAPI là dịch vụ API chuyên cung cấp dữ liệu giá xăng dầu bán lẻ tại Việt Nam theo định dạng JSON. Dữ liệu được tổng hợp từ 11 nguồn uy tín (bao gồm Petrolimex và các mirror Petrolimex, PVOil, Mipec, COMECO, Saigon Petro, PetroTimes, WebGia, GiaXangHomNay) và cập nhật tự động theo lịch điều hành (Nghị định 80/2023).

Hệ thống hỗ trợ tra cứu giá theo 63 tỉnh thành với phân biệt rõ ràng Vùng 1 (giá chuẩn) và Vùng 2 (giá cao hơn tối đa 2%) theo đúng quy định hiện hành.

[!IMPORTANT] Dự án này là dự án cộng đồng phục vụ học tập và nghiên cứu kỹ thuật, không đại diện cho bất kỳ tổ chức, doanh nghiệp hoặc cơ quan nhà nước nào.

✨ Tính năng nổi bật

• 🚀 Hiệu năng cực cao: Dữ liệu phục vụ từ RAM (In-memory cache), độ trễ < 10ms.

• 🔄 Cập nhật tự động: Adaptive Cron thông minh bắt nhịp chính xác chu kỳ điều chỉnh giá của nhà nước.

• 🔗 11 nguồn dữ liệu: Tích hợp công nghệ Bot Stealth Fallback thông minh, vượt rào chống bot.

• 🗺️ 63 Tỉnh thành: Tra cứu giá theo từng tỉnh/thành, bao gồm thông tin Vùng 1/2.

• 🛡️ Phân vùng chính xác: Phân loại đúng 15 tỉnh Vùng 2 toàn tỉnh, 4 tỉnh bán phần (partial).

• 🔒 Rate Limiting: Bảo vệ API khỏi lạm dụng (60 req/phút cho source quốc gia, 20 req/phút cho tỉnh thành).

• 🌍 Cache-Control chuẩn HTTP: Hỗ trợ CDN caching, giúp người dùng cuối nhận data siêu nhanh.

• 🔑 Không cần Auth: Mở cửa cho mọi nhà phát triển, hỗ trợ CORS đầy đủ.

🚀 Bắt đầu nhanh

# Clone repository
git clone https://github.com/TranQui004/vietfuel-api.git
cd vietfuel-api

# Cài đặt dependencies backend
cd backend
npm install

# Khởi chạy server (development)
npm run dev

Server mặc định tại: http://localhost:3000

Giao diện web được phục vụ cùng cổng backend:

• Trang chủ: http://localhost:3000/
• Live Data: http://localhost:3000/live

Nếu chạy từ thư mục gốc project:

npm --prefix backend run dev

🚀 Triển Khai Production (PM2)

Dự án đã bao gồm file ecosystem.config.js để triển khai với PM2 – tiêu chuẩn vận hành Node.js trên Server thật:

# Cài PM2 toàn cục (nếu chưa có)
npm install -g pm2

# Khởi động với PM2
pm2 start ecosystem.config.js --env production

# Quản lý tiến trình
pm2 status
pm2 logs vietfuel-api
pm2 restart vietfuel-api

📡 Danh sách Endpoint

Nhóm Quốc gia

Tỉnh thành (on-demand)

Hệ thống

Giao diện web

🗺️ Phân vùng giá xăng dầu

Theo quy định, giá xăng dầu tại Việt Nam được phân thành 2 vùng:

15 tỉnh thuần Vùng 2: Hà Giang, Cao Bằng, Bắc Kạn, Tuyên Quang, Lào Cai, Điện Biên, Lai Châu, Sơn La, Yên Bái, Lạng Sơn, Kon Tum, Gia Lai, Đắk Lắk, Đắk Nông, Lâm Đồng.

4 tỉnh bán phần (một số huyện thuộc Vùng 2):

API trả về thêm field partialRegion: true và vung2Districts cho 4 tỉnh này.

🛠️ Công nghệ sử dụng

• Backend: Node.js v22+, Express, express-rate-limit, helmet, compression.
• Scraping: node-fetch + cheerio — HTTP-only, không Playwright/headless browser.
• Cache: node-cache (In-memory) + disk persistence (cache.json).
• Scheduler: node-cron — lịch thích ứng 3 chế độ theo Nghị định 80/2023/NĐ-CP:
  • T2–T4: 4 tiếng/lần (Checking)
  • T5, 14:30–16:00: 15 phút/lần (Hunting — khung giờ điều chỉnh giá)
  • T6–CN: 6 tiếng/lần (Maintenance)
• Frontend: EJS templates + Vanilla CSS/JS — serve trực tiếp bởi Express (không framework JS riêng).
• API Testing: API Playground tùy chỉnh tại /playground (thay thế Swagger UI).
• Logging: Winston.

📁 Cấu trúc dự án

├── backend/
│   ├── index.js              # Entry point Express + static serving
│   ├── config/
│   │   └── index.js          # Cấu hình chung (port, URLs, cron, cache TTL)
│   ├── data/
│   │   └── provinces.json    # Từ điển 63 tỉnh thành (slug, region, districts)
│   ├── routes/
│   │   └── fuel.js           # Toàn bộ REST API endpoints
│   ├── services/
│   │   ├── scrapers/         # Mỗi file là một engine HTTP-only độc lập
│   │   │   ├── utils.js          # Hàm core dùng chung (parsePrice, UA pool, ...)
│   │   │   ├── petrolimex.js     # Petrolimex — Tier 0: VIEApps REST API
│   │   │   ├── pvoil.js          # PVOil — Tier 0: IP origin bypass Cloudflare
│   │   │   ├── pvoil-parser.js   # Parser HTML/text cho PVOil
│   │   │   ├── mipec.js          # Mipec — HTTP + cheerio
│   │   │   ├── comeco.js         # COMECO — HTTP + cheerio
│   │   │   ├── saigonpetro.js    # Saigon Petro — dynamic API
│   │   │   ├── petrotimes.js     # Petro Times — internal API
│   │   │   ├── webgia.js         # WebGia — HTTP + cheerio
│   │   │   └── giaxanghomnay.js  # GiaXangHomNay — HTTP + cheerio
│   │   ├── scraper.js        # Index tổng hợp — xuất tất cả scraper functions
│   │   └── cache.js          # In-memory cache (node-cache) + disk fallback
│   ├── workers/
│   │   └── jobs.js           # Adaptive Cron scheduler (3 chế độ)
│   ├── utils/
│   │   ├── logger.js         # Winston logger
│   │   └── fuel-helpers.js   # Helper tổng hợp: merge, normalize, sort
│   └── tests/
│       ├── scrapers/         # Smoke tests cho từng scraper
│       ├── api/              # API integration tests
│       └── run-all.js        # Chạy toàn bộ test suite
├── frontend/
│   ├── views/                # EJS templates (serve bởi Express)
│   │   ├── index.ejs         # Trang chủ
│   │   ├── live.ejs          # Live Data Dashboard
│   │   ├── endpoints.ejs     # API Reference
│   │   ├── playground.ejs    # API Playground (test endpoint tương tác)
│   │   └── partials/         # Header, Footer components
│   ├── css/
│   │   ├── style.css         # Global CSS
│   │   └── playground.css    # CSS riêng cho Playground
│   ├── js/
│   │   ├── live.js           # Live Data Dashboard logic
│   │   ├── playground.js     # API Playground logic
│   │   └── lang.js           # i18n (VI/EN)
│   └── brand/                # Logo, banner assets
├── docs/
│   ├── assets/               # Ảnh preview cho README
│   ├── vi/                   # Tài liệu tiếng Việt
│   └── en/                   # Tài liệu tiếng Anh
├── cache.json                # Disk persistence cache (root)
└── ecosystem.config.js       # Cấu hình PM2 cho production

📚 Tài liệu chi tiết

• Kiến trúc hệ thống
• Lịch sử cập nhật
• Quy ước comment
• Xem tài liệu API trực tuyến

🤝 Pháp lý & Cộng đồng

• Chỉ mục pháp lý
• Hướng dẫn đóng góp (CONTRIBUTING.md)
• Quy tắc ứng xử
• Chính sách bảo mật
• Hỗ trợ

Tài nguyên nên push lên GitHub

• Toàn bộ mã nguồn backend/, frontend/, docs/
• Các file markdown cộng đồng/pháp lý
• Cấu hình chạy production (ecosystem.config.js)

Tài nguyên không nên push

• node_modules/, logs/, file dump debug, cache runtime
• Mọi file chứa credential hoặc thông tin nhạy cảm (.env)

⚖️ Giấy phép

Phân phối dưới giấy phép MIT. Xem LICENSE để biết thêm chi tiết.

© 2026 TranQui - GitHub: TranQui004
Built with ❤️ by Developers for Developers.