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.

📖 Mục lục

Giới thiệu
Tính năng nổi bật
Sử dụng API
Danh sách Endpoint
Chạy Local (cho Developer)
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ừ cache, độ trễ thấp.
🔄 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.
📊 Giao diện trực quan: Hai trang Dashboard được thiết kế bằng ApexCharts.
- Bảng dữ liệu Live (/): Cập nhật tự động từng phút theo chế độ Dark/Light mode, hiển thị so sánh giá trên toàn quốc với hơn 63 tỉnh thành.
- Bảng Thống kê tổng quan (/history): Biểu đồ cột ghép (Grouped Column) so sánh giá Vùng 1 và Vùng 2, kết hợp bảng dữ liệu thị trường có tính năng Lọc (Filter) theo nguồn và Sắp xếp (Sort) cột thông minh.
🖥️ CLI Console Dashboard: Tiện ích tương tác qua dòng lệnh (npm run cli) giúp quản trị viên tra cứu giá, xem lịch sử, kiểm tra sức khỏe hệ thống và dọn dẹp bộ nhớ đệm mà không cần trình duyệt.
🗺️ 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).
🔑 Không cần Auth: Mở cửa cho mọi nhà phát triển, hỗ trợ CORS đầy đủ.

🌐 Sử dụng API

API được host sẵn tại địa chỉ công khai. Bạn có thể gọi trực tiếp mà không cần cài đặt bất kỳ thứ gì:

# Lấy giá xăng dầu tổng hợp (tất cả nguồn)
curl https://vietfuel-api.tranqui.workers.dev/api/fuel-prices

# Lấy giá từ nguồn cụ thể
curl https://vietfuel-api.tranqui.workers.dev/api/fuel-prices/petrolimex

# Tra cứu giá theo tỉnh/thành
curl https://vietfuel-api.tranqui.workers.dev/api/fuel-prices/province/ha-noi

Giao diện trực quan:

🏠 Trang chủ: https://vietfuel-api.tranqui.workers.dev/
📊 Live Data: https://vietfuel-api.tranqui.workers.dev/live
📈 Thống kê & Lịch sử: https://vietfuel-api.tranqui.workers.dev/history
🔬 Test API: https://vietfuel-api.tranqui.workers.dev/test-api

📡 Danh sách Endpoint

Nhóm Quốc gia

Phương thức	Endpoint	Mô tả
`GET`	`/api/fuel-prices`	(Khuyên dùng) Trả về dữ liệu gộp từ tất cả 11 nguồn
`GET`	`/api/fuel-prices/:source`	Nguồn cụ thể: `petrolimex`, `kv2_petrolimex`, `saigon_petrolimex`, `vungtau_petrolimex`, `pvoil`, `mipec`, `comeco`, `saigonpetro`, `petrotimes`, `webgia`, `giaxanghomnay`

Tỉnh thành (on-demand)

Phương thức	Endpoint	Mô tả
`GET`	`/api/provinces`	Danh sách 63 tỉnh thành với `id`, `slug`, `region`
`GET`	`/api/provinces?region=2`	Lọc chỉ tỉnh thuộc Vùng 2
`GET`	`/api/fuel-prices/province/:slug`	Giá xăng dầu theo tỉnh (VD: `/api/fuel-prices/province/ha-noi`)

Hệ thống & Lịch sử

Phương thức	Endpoint	Mô tả
`GET`	`/api/health`	Trạng thái sức khoẻ toàn bộ 11 nguồn dữ liệu
`GET`	`/api/sources`	Danh sách 11 nguồn dữ liệu kèm trạng thái cache
`GET`	`/api/history`	Lịch sử giá (hỗ trợ query `?limit=` và filter theo `/api/history/:fuel_name`)

Phản hồi mẫu

{
  "success": true,
  "status": "ok",
  "meta": {
    "primarySource": "Petrolimex",
    "priceDate": "2026-05-15",
    "priceDateDisplay": "15/05/2026",
    "sourceCount": 11,
    "totalItems": 7
  },
  "data": [
    { "name": "Xăng RON 95-V", "region1": 24730, "region2": 25220, "unit": "VND/lít" },
    { "name": "Xăng RON 95-III", "region1": 24330, "region2": 24810, "unit": "VND/lít" }
  ]
}

💻 Chạy Local (cho Developer)

Để chạy thử nghiệm dự án hoặc phát triển tính năng mới tại local:

git clone https://github.com/TranQui004/vietfuel-api.git
cd petrolimex-fuel-api

# Cài đặt thư viện
npm install

# Khởi chạy server local (Wrangler dev)
npx wrangler dev

Mở trình duyệt truy cập: http://localhost:8787

🖥️ Khởi chạy Console Dashboard (CLI)

Sau khi khởi động server, bạn có thể khởi chạy giao diện tương tác CLI (không cần trình duyệt) bằng lệnh:

npm run cli

💻 Tự vận hành (Self-Hosted)

Dự án cung cấp mã nguồn mở hoàn toàn để bạn có thể tự vận hành (self-host) API của riêng mình nếu không muốn sử dụng public endpoint.

Tuỳ chọn 1: Cloudflare Workers (Khuyên dùng)

Bạn có thể tự host API này trên Cloudflare Workers miễn phí (Free tier: 100,000 req/ngày):

Tạo tài khoản Cloudflare tại cloudflare.com (miễn phí)
Tạo KV Namespace trên Dashboard: Workers & Pages → KV → Create namespace đặt tên FUEL_CACHE
Tạo D1 Database (Tuỳ chọn cho lịch sử giá): Workers & Pages → D1 → Create database đặt tên vietfuel-history
Sửa wrangler.toml: Thay các ID tương ứng vừa tạo.
Deploy:

npx wrangler login
npx wrangler d1 execute vietfuel-history --file=./backend/src/db/schema.sql
npx wrangler deploy

Tuỳ chọn 2: Docker (Optional / Advanced)

Nếu bạn có VPS riêng và không muốn phụ thuộc vào hệ sinh thái Cloudflare, bạn có thể chạy API qua Docker (sử dụng in-memory cache và SQLite thay thế).

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

# Khởi chạy qua Docker Compose
docker-compose up -d

Lưu ý: Chế độ Docker sử dụng node-server.js thay vì Cloudflare Workers environment. API Lịch sử giá sẽ được ghi vào file cục bộ.

🗺️ 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:

Vùng	Mô tả	Số tỉnh
Vùng 1	Địa bàn gần kho đầu mối, hạ tầng thuận lợi. Giá tiêu chuẩn.	43 tỉnh (toàn tỉnh)
Vùng 2	Địa bàn xa cảng, xa kho đầu mối, vùng sâu, vùng xa. Giá cao hơn tối đa 2%.	15 tỉnh (toàn tỉnh) + 4 tỉnh bán phần

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):

Tỉnh	Huyện Vùng 2
Quảng Ninh	Vân Đồn, Cô Tô, Hải Hà
Bình Thuận	Phú Quý
Bà Rịa - Vũng Tàu	Côn Đảo
Kiên Giang	Phú Quốc, Kiên Hải

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

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

Runtime: Cloudflare Workers (V8 isolates) + Hono framework.
Scraping: fetch + cheerio — HTTP-only, hoàn toàn không cần Headless Browser.
Cache: Cloudflare KV (FUEL_CACHE) — dữ liệu được phục vụ từ edge gần người dùng nhất.
Scheduler: Cloudflare Cron Triggers — lịch thích ứng theo Nghị định 80/2023/NĐ-CP.
Frontend: HTML/CSS/JS tĩnh — phục vụ qua Cloudflare CDN, không cần framework JS.

📁 Cấu trúc dự án

├── backend/
│   └── src/
│       ├── index.js              # Entry point Hono + router
│       ├── scraper.js            # Unified scraper entry point
│       ├── cache.js              # Cloudflare KV helpers
│       ├── scrapers/             # Thư mục chứa logic cào dữ liệu độc lập
│       │   ├── petrolimex.js     # Petrolimex (REST API nội bộ)
│       │   ├── pvoil.js          # PVOil (Bypass Cloudflare)
│       │   ├── mipec.js          # Mipec
│       │   ├── comeco.js         # COMECO
│       │   ├── saigonpetro.js    # Saigon Petro
│       │   ├── petrotimes.js     # Petro Times
│       │   ├── webgia.js         # WebGia (mirror Petrolimex)
│       │   └── giaxanghomnay.js  # GiaXangHomNay (63 tỉnh)
│       ├── db/
│       │   ├── repository.js     # Lịch sử Giá (D1/SQLite)
│       │   └── schema.sql        # Cấu trúc bảng lịch sử
│       ├── data/
│       │   └── provinces.json    # Dataset 63 tỉnh thành (slug, region, districts)
│       └── utils/
│           └── fuel-helpers.js   # Normalize, sort, build response
├── public/                       # Frontend assets (HTML, CSS, JS, hình ảnh)
│   ├── index.html                # Trang chủ
│   ├── live.html                 # Dashboard dữ liệu trực tiếp
│   ├── history.html              # Dashboard Thống kê & Lịch sử
│   ├── endpoints.html            # Tài liệu API Reference
│   ├── test-api.html             # Công cụ Test API trực quan
│   ├── css/                      # Stylesheet
│   ├── js/                       # JS tương tác giao diện (bao gồm history.js)
│   └── brand/                    # Logo & Banner
├── docs/                         # Tài liệu kỹ thuật đa ngôn ngữ (VI/EN)
├── wrangler.toml                 # Cấu hình Cloudflare Workers (template)
└── package.json

📚 Tài liệu chi tiết

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

⚖️ Giấy phép

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

Name		Name	Last commit message	Last commit date
.github		.github
backend		backend
dist		dist
docs		docs
frontend		frontend
public		public
tools		tools
.gitignore		.gitignore
CHANGELOG.en.md		CHANGELOG.en.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
ecosystem.config.js		ecosystem.config.js
package-lock.json		package-lock.json
package.json		package.json
wrangler.toml		wrangler.toml

Navigation Menu

Repository files navigation

VietFuelAPI

📖 Mục lục

👋 Giới thiệu

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

🌐 Sử dụng API

📡 Danh sách Endpoint

Nhóm Quốc gia

Tỉnh thành (on-demand)

Hệ thống & Lịch sử

Phản hồi mẫu

💻 Chạy Local (cho Developer)

🖥️ Khởi chạy Console Dashboard (CLI)

💻 Tự vận hành (Self-Hosted)

Tuỳ chọn 1: Cloudflare Workers (Khuyên dùng)

Tuỳ chọn 2: Docker (Optional / Advanced)

🗺️ 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

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

VietFuelAPI

📖 Mục lục

👋 Giới thiệu

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

🌐 Sử dụng API

📡 Danh sách Endpoint

Nhóm Quốc gia

Tỉnh thành (on-demand)

Hệ thống & Lịch sử

Phản hồi mẫu

💻 Chạy Local (cho Developer)

🖥️ Khởi chạy Console Dashboard (CLI)

💻 Tự vận hành (Self-Hosted)

Tuỳ chọn 1: Cloudflare Workers (Khuyên dùng)

Tuỳ chọn 2: Docker (Optional / Advanced)

🗺️ 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

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages