API lịch sử giá sản phẩm của Kèo Quỷ — miễn phí hoàn toàn, không cần auth, hỗ trợ CORS, phù hợp để tra cứu biến động giá, phân tích xu hướng và xây dashboard theo thời gian thực gần đúng.
searchTìm sản phẩm theo từ khóa để lấy item_key chuẩnproductXem timeline giá, summary và dữ liệu dự đoán của một sản phẩmstatsLấy số liệu tổng quan để hiển thị dashboard hoặc landing pagetopPhân tích sản phẩm nổi bật theo tháng và điểm xếp hạngTìm kiếm sản phẩm theo tên. Endpoint này thường là bước đầu tiên để lấy item_key trước khi gọi API chi tiết lịch sử giá.
| Tên | Kiểu | Mô tả | |
|---|---|---|---|
| q | string | required | Từ khóa tìm kiếm, tối thiểu 2 ký tự |
| page | number | optional | Trang hiện tại, mặc định 1 |
| per_page | number | optional | Số item mỗi trang, tối đa 30, mặc định 15 |
{
"ok": true,
"q": "iphone",
"items": [
{
"platform": "shopee",
"item_key": "358123846:11402699882",
"name": "iPhone 15 128GB Chính Hãng",
"shop_name": "Apple Flagship Store",
"image_url": "https://.../image.webp",
"product_url": "https://shopee.vn/...",
"appearances_30d": 18,
"best_price": 18990000,
"best_discount": 17,
"last_seen_at": "2026-04-24T10:30:00+07:00"
}
],
"pagination": {
"page": 1,
"per_page": 15,
"total": 248
}
}appearances_30d — số lần sản phẩm được hệ thống ghi nhận trong 30 ngày gần nhấtbest_price — mức giá thấp nhất từng ghi nhận trong giai đoạn theo dõi hiện cóbest_discount — phần trăm giảm giá tốt nhất từng thấyitem_key — khóa định danh để gọi endpoint chi tiết
/api/v1/history/search?q=iphone&page=1&per_page=15Lấy chi tiết lịch sử giá của một sản phẩm. Đây là endpoint chính để hiển thị summary, timeline biến động giá và dữ liệu dự đoán.
| Tên | Kiểu | Mô tả | |
|---|---|---|---|
| item_key | string | required | Định dạng shopid:itemid, ví dụ 358123846:11402699882 |
| days | number | optional | Số ngày lịch sử cần lấy, từ 7–90, mặc định 30 |
{
"ok": true,
"item_key": "358123846:11402699882",
"days": 30,
"summary": {
"name": "iPhone 15 128GB Chính Hãng",
"shop_name": "Apple Flagship Store",
"image_url": "https://.../image.webp",
"product_url": "https://shopee.vn/...",
"rating_star": 4.9,
"rating_total": 1324,
"sold_hint": "Đã bán 5,2k+",
"is_shop_official": true,
"is_shop_preferred": false,
"appearances": 18,
"best_price": 18990000,
"worst_price": 21990000,
"avg_price": 20150000,
"latest_price": 19490000,
"live_discount_pct": 11,
"best_discount": 17,
"price_level": "low",
"first_seen_at": "2026-03-25T08:00:00+07:00",
"last_seen_at": "2026-04-24T10:30:00+07:00"
},
"timeline": [
{"seen_at": "2026-04-20T10:00:00+07:00", "price": 19990000, "discount_pct": 8},
{"seen_at": "2026-04-24T10:30:00+07:00", "price": 19490000, "discount_pct": 11}
],
"prediction": {
"direction": "stable",
"confidence": 0.71
}
}summary — thông tin tổng hợp hiện tại và thống kê giá của sản phẩmtimeline — chuỗi dữ liệu theo thời gian để vẽ biểu đồ giáprediction — vùng dữ liệu dự đoán, có thể thay đổi theo version backend
/api/v1/history/product/358123846:11402699882?days=30Lấy số liệu tổng quan của hệ thống lịch sử giá. Phù hợp để hiển thị widget thống kê hoặc health snapshot.
{
"ok": true,
"total_products": 582341,
"new_products_today": 421,
"last_updated": "2026-04-24T10:30:00+07:00"
}/api/v1/history/statsLấy danh sách sản phẩm top theo khoảng tháng. Thích hợp để làm bảng xếp hạng, trang khám phá sản phẩm nổi bật hoặc phân tích mức độ xuất hiện.
| Tên | Kiểu | Mô tả | |
|---|---|---|---|
| months | number | optional | Số tháng cần thống kê, mặc định 1 |
{
"ok": true,
"months": 1,
"items": [
{
"period_month": "2026-04",
"platform": "shopee",
"item_key": "358123846:11402699882",
"name": "iPhone 15 128GB Chính Hãng",
"score": 97.4,
"appearances": 18,
"best_price": 18990000,
"avg_discount": 12.6,
"rank_no": 1
}
]
}/api/v1/history/top?months=1// Tìm sản phẩm để lấy item_key const search = await fetch('https://keoquy.com/api/v1/history/search?q=iphone').then(r => r.json()); const itemKey = search.items[0]?.item_key; // Lấy lịch sử giá chi tiết const detail = await fetch(`https://keoquy.com/api/v1/history/product/${itemKey}?days=30`).then(r => r.json()); console.log(detail.summary.name, detail.summary.best_price); // Lấy thống kê tổng quan const stats = await fetch('https://keoquy.com/api/v1/history/stats').then(r => r.json()); console.log(stats.total_products);
# Tìm kiếm sản phẩm curl "https://keoquy.com/api/v1/history/search?q=iphone&page=1&per_page=15" # Xem lịch sử giá sản phẩm curl "https://keoquy.com/api/v1/history/product/358123846:11402699882?days=30" # Thống kê tổng quan curl "https://keoquy.com/api/v1/history/stats" # Top sản phẩm 1 tháng curl "https://keoquy.com/api/v1/history/top?months=1"
import requests base = "https://keoquy.com/api/v1/history" # Bước 1: tìm sản phẩm search = requests.get(base + "/search", params={"q": "iphone"}).json() item_key = search["items"][0]["item_key"] # Bước 2: lấy lịch sử giá 30 ngày detail = requests.get(base + f"/product/{item_key}", params={"days": 30}).json() print(detail["summary"]["name"], detail["summary"]["latest_price"]) # Bước 3: lấy bảng top top = requests.get(base + "/top", params={"months": 1}).json()
• Base URL: https://keoquy.com
• Tất cả endpoint ở trang này đều chạy dưới prefix /api/v1/history
• CORS đã bật, có thể gọi trực tiếp từ frontend trình duyệt
• Miễn phí hoàn toàn, không cần API key
• Rate limit: 60 requests/phút
• Dữ liệu được hệ thống cập nhật mỗi 30 phút tự động
• item_key có dạng shopid:itemid
• Nên gọi search trước để lấy đúng khóa định danh thay vì tự đoán
• Một số field trong prediction hoặc timeline có thể được mở rộng thêm theo backend
{ "ok": false, "error": "Invalid query" }
// 400 — Tham số không hợp lệ (vd: q quá ngắn, days ngoài khoảng 7-90)
// 404 — Không tìm thấy sản phẩm hoặc item_key không tồn tại
// 429 — Vượt rate limit, chờ khoảng 60 giây
// 500 — Lỗi hệ thống, thử lại sau