# DuLieu.dev — Vietnamese Economic Data API

> Daily-updated Vietnamese economic data: exchange rates, gold, silver, fuel, coffee, pepper, interest rates, crude oil, grocery prices (56K+ products), drug & pharmacy prices (12K+ products), electronics prices (80K+ products, 5 retailers), perfume & cosmetics prices (3 fragrance retailers, per-size rows with VND/ml), cake & bakery prices (2 bakeries, with size/weight/flavour/occasion), real-estate listings (batdongsan.com.vn + guland.vn + nhatot.com, sale & rent, all property types) with seller/agency profiles with planning/zoning (quy hoạch) map tile layers, area price benchmarks & the official land-price schedule (Bảng giá đất 2026), weather (70+ cities), forecasts, lottery (41 provinces), CPI. 42 crawlers, 40+ banks, COICOP classification.

## API Access

Base URL: https://dulieu.dev
Authentication: API key required (Bearer token or ?api_key= query param)
Get your key: https://dulieu.dev/settings (Google sign-in)
MCP monolithic: https://dulieu.dev/mcp (all 23 public tools, Bearer or opaque URL)
MCP sub-servers:
  - https://dulieu.dev/mcp/dulieu-finance — exchange_rates, gold, silver, interest_rates, commodities (5 tools)
  - https://dulieu.dev/mcp/dulieu-weather — weather, weather_forecast (2 tools)
  - https://dulieu.dev/mcp/dulieu-retail — fuel, coffee, pepper, groceries, drugs, electronics (6 tools)
  - https://dulieu.dev/mcp/dulieu-realestate — resolve_geo, get_realestate_listings, get_realestate_summary, get_realestate_planning, get_realestate_land_prices, get_realestate_agents, estimate_realestate_price, fetch_realestate_live (8 tools)
  - https://dulieu.dev/mcp/dulieu-reference — daily_summary, provinces_merge (2 tools)
  Each sub-server exposes a focused tool set to reduce context window usage.

## Quick Start

```
curl -H "Authorization: Bearer dl_YOUR_KEY" https://dulieu.dev/api/summary
```

## Endpoints (Free Plan — 100 calls/day)

- GET /api/summary — Daily briefing of all data, incl. MST company-registry KPI & real-estate top provinces (best for AI agents). ?at=YYYY-MM-DD for a record-time as-of view (carry-forward: latest data ≤ that date; echoes as_of + resolved{} per series)
- GET /api/snapshot — Record-time cross-source metric snapshot (?at=ISO/date or now). Nearest stored snapshot ≤ T, else live fallback; `cached` flag shows which
- GET /api/exchange — Currency exchange rates (20 currencies, VND). Filters: date, from, to, limit (default 500)
  Human page: https://dulieu.dev/ty-gia — today's Vietcombank board (cash buy / transfer buy / sell, đồng per unit) for 9 currencies, 7/30/90-day change and USD charts.
  One page per currency: https://dulieu.dev/ty-gia/{usd,eur,cny,jpy,krw,gbp,aud,sgd,thb} — that currency's three rates, buy/sell spread, 7/30/90-day change, 90-day high/low, conversion to đồng at the listed rates, last 10 readings, 30/90-day charts.
- GET /api/gold — Gold prices (SJC, DOJI, 8+ types). Filters: date, from, to, limit (default 500)
  Human page: https://dulieu.dev/gia-vang — today's DOJI board (buy/sell, nghìn đồng/chỉ), 7/30/90-day change and charts for SJC and Nhẫn 9999.
  One page per DOJI gold product: https://dulieu.dev/gia-vang/sjc, /gia-vang/nhan-9999, /gia-vang/nu-trang-9999, /gia-vang/nu-trang-999, /gia-vang/nu-trang-99, /gia-vang/nguyen-lieu-9999, /gia-vang/nguyen-lieu-999 — buy/sell, buy/sell spread, 7/30/90-day change, 90-day high/low, price by weight (chỉ, lượng), last readings, 30/90-day charts.
- GET /api/silver — Silver prices (11 types). Filters: date, from, to, limit (default 500)
  Human page: https://dulieu.dev/gia-bac — today's domestic 999 silver prices from the CafeF board (1-lượng and 1-kg products only, buy/sell in đồng), change from the previous reading, 7/30/90-day change and 30/90-day charts. Data: GET /api/silver (rows with source = cafef.vn; prices in nghìn đồng, see `unit` — a multi-lượng bar row is priced per bar).
- GET /api/fuel — Fuel prices (6 types, 2 zones). Filters: date, from, to, limit (default 500)
  Human page: https://dulieu.dev/gia-xang — today's retail fuel prices from the VnExpress board (E5 RON 92, E10 RON 95-III, Diesel per litre; Mazut per kg), the recent price steps with their change, 7/30/90-day change and 30/90-day charts. Data: GET /api/fuel/vnexpress.
- GET /api/coffee — Domestic coffee prices (4 regions). Filters: date, from, to, limit (default 500)
  Human page: https://dulieu.dev/gia-ca-phe — today's domestic coffee prices from the giacaphe.com board (Đắk Lắk, Lâm Đồng, Gia Lai, Đắk Nông, đồng/kg), the recent reading days with their change, 7/30/90-day change and 30/90-day charts. Data: GET /api/coffee (rows with source = giacaphe.com).
- GET /api/pepper — Pepper prices (domestic 5 regions + international India Kochi). Filters: date, from, to, limit (default 500)
- GET /api/interest — Bank interest rates (40+ banks, 8 terms)
  Human page: https://dulieu.dev/lai-suat — today's retail savings rates from the banks' own schedules (Vietcombank, BIDV, VPBank), demand to 36 months, %/year, 7/30/90-day change in percentage points and 12-month charts.
- GET /api/commodities — All commodity prices (crude oil, coffee futures). Filters: date, from, to, limit (default 500)
- GET /api/indicators — Economic indicators (CPI, inflation, IIP). Filters: date, from, to, limit (default 500)
- GET /api/weather — Weather for 70+ cities (all province capitals + tourist destinations). Filters: date, from, to, city, limit (default 500)
- GET /api/weather/forecast — 5-day weather forecast for 70+ cities. With no date filter returns UPCOMING targets only (target_date >= today); pass date/from/to for the archive. Filters: city, limit (default 3000)
- GET /api/weather/summary — Today's weather summary for all cities
- GET /api/lottery — Lottery results (north/central/south, 41 provinces, 2 sources). Supports ?source=cafef.vn|minhngoc.net.vn. Filters: date, from, to, limit (default 500)
- GET /api/holidays/vn — Vietnamese public holidays (Bộ luật Lao động 2019, Art. 112). Computed lunar→Gregorian + nghỉ bù + govt decree overrides. Params: ?year=YYYY (default current), ?date=YYYY-MM-DD (single check), ?from=&to= (range). Includes Tết Nguyên Đán (5 lunar days), Giỗ Tổ Hùng Vương (lunar 10/3), Ngày Văn hóa VN (from 2026). 11 statutory days/year (12 from 2026)
- GET /api/geo — Vietnamese administrative geography
- GET /api/plans — Available plans and features
- GET /api/bakery — Cake & bakery prices (givralbakery.com.vn, cailonuong.com), with size_cm, weight_g, tiers, flavour and occasion. NOTE: price is NULLABLE — a large share of the Givral catalogue is quoted on request ("Liên hệ"). Pass priced=1 for listed prices only. Filter by store/occasion/flavour/category
- GET /api/bakery/summary — Cake summary grouped by occasion: counts, priced vs quoted-on-request, price range, avg diameter
- GET /api/bakery/catalog — Full deduplicated cake catalog: latest price per product across all crawl dates. Filters: store, occasion, flavour, limit (default 50000)
- GET /api/bakery/search?q= — Live cake-name search (ILIKE, deduplicated to latest price). Filters: store, occasion, limit (default 50)
- GET /api/cosmetics — Perfume & cosmetics prices (namperfume.net, orchard.vn, thegioinuochoa.com.vn). One row per sellable SIZE, with volume_ml, concentration (EDP/EDT/Extrait/Parfum/EDC/Cologne), gender, EAN barcode and price_per_ml. Filter by store/brand/concentration/gender/barcode/category
- GET /api/cosmetics/summary — Fragrance summary grouped by concentration: counts, brands, price range, avg VND/ml, avg discount
- GET /api/cosmetics/compare — Same EAN priced at more than one retailer, ranked by spread between cheapest and dearest
- GET /api/cosmetics/catalog — Full deduplicated perfume catalog: latest price per product across all crawl dates. Filters: store, brand, concentration, gender, limit (default 50000)
- GET /api/cosmetics/search?q= — Live perfume-name search (ILIKE, deduplicated to latest price). Filters: store, brand, concentration, limit (default 50)
- GET /api/electronics — Electronics prices — phones, laptops, appliances & PC/components (TGDD, CellphoneS, FPT Shop, Hoang Ha Mobile, Di Dong Viet, Nguyen Kim, Dien May Xanh, GearVN, Tan Doanh, …). Filter by store/brand/category
- GET /api/electronics/summary — Store-level summary with avg prices, brands, ratings
- GET /api/electronics/stores — Store product counts
- GET /api/electronics/catalog — Full deduplicated catalog: latest priced reading per product seen in the last 14 days (not just the latest crawl slice; same set as /electronics/stores `products`). Filters: store, brand, category, limit (default 200000)
- GET /api/electronics/search?q= — Live product-name search (ILIKE, deduplicated to latest price per product, _raw stripped). Filters: store, brand, category, limit (default 50)
- GET /api/realestate — Real-estate listings from batdongsan.com.vn + guland.vn + nhatot.com (sale & rent, all property types). Filters: transaction (ban|cho-thue), type/property_type, province, district, source, q (keyword search, accent-insensitive over title/district/location), min_price/max_price (VND), min_area/max_area (m²), has_image=1, date range, limit, offset. With no date filter it serves the newest complete crawl day, named in meta.snapshot_date (today's crawl lands ~03:30–08:00 ICT; until it is mostly in, the previous day is served). Returns meta.total for pagination. Each listing includes `images: string[]` (photo gallery; nhatot 3-10 photos, guland 3-5 carousel images; falls back to `[image]` for sources with single thumbnails).
- GET /api/realestate/by-id/:source_id — Single listing lookup by source_id (URL-encoded). Returns the latest crawled snapshot with cached_image and images array.
- GET /api/realestate/suggest?q=<prefix>&limit=N — Location typeahead/autocomplete. Accent-insensitive prefix/substring match over province/district/ward names with listing counts. Returns `{ type, name, province, district?, slug, listing_count }`. Cached rollup, <100ms. Prefix matches ranked first, then by listing_count desc.
- GET /api/realestate/facets — Distinct filter values with counts: provinces (63), property_types, sources (guland/batdongsan/nhatot), transactions (ban/cho-thue). When province is specified, also returns districts and wards arrays. Supports cross-filtering via query params (province, type, transaction, source, date range). Use for building dynamic filter dropdowns.
- GET /api/realestate/sources/stats — Per-source organic-activity ranking: all-time distinct listings (total), last-crawl freshness, NEW-listing counts by first-seen window (added_24h/7d/N-day = the "new posts per N days" analog) + per_day rate, and sale/rent + property-type skew on the latest crawl-date snapshot. ?days=N (default 30).
- GET /api/realestate/summary — Market snapshot: median (+ trimmed avg) price, price/m² & area by province × transaction × property type (all 63 provinces)
- GET /api/realestate/stores — Listing counts & latest crawl date by province × transaction
- GET /api/realestate/trends — Daily market trend: listings count, avg & median price/m², avg price/area (filters: days, province, transaction, type)
- GET /api/realestate/movers — Listings whose price changed between their two latest crawl snapshots (needs ≥2 crawl days)
- GET /api/realestate/planning — Guland planning/zoning map (quy hoạch) tile layers per province: land-use 2021-2030 + general planning + base land, each with an {z}/{x}/{y} XYZ tile URL template, max zoom, source year, GSO codes (filter: province)
- GET /api/realestate/benchmarks — Area-level price benchmarks: median/avg price-per-m² per source × province × district × transaction × segment (filters: province, transaction, source, limit)
- GET /api/realestate/estimate — Comps-based price estimate for a specific property: most-specific tier with enough comps (project→street→ward→district→province) × area → estimate + p25–p75 band + tier + confidence + comps (params: province, district, ward, street, project, type=apt|house|land, transaction, area, refresh). Set refresh=1 to also fetch a targeted realtime source query (nhatot keyword) + upsert before estimating. Descriptive only — floor/alley/depth not modeled.
- GET /api/realestate/fetch — On-demand realtime fetch + upsert (no estimate): searches the nhatot Chợ Tốt gateway by keyword (project→street→district) and upserts arriving listings/agents into the DB (params: province, district, street, project, max_pages). Explicit opt-in; 60s per-query throttle.
- GET /api/realestate/land-prices — Official land-price schedule (Bảng giá đất 2026) per street × land type, 4 position tiers (VNĐ/m²); covers every ward & street, HCMC ≈ 35K rows (filters: province, ward, land_type, q, limit)
- GET /api/realestate/agents — Real-estate sellers (nhatot.com + guland.vn) with active-listing counts (live_ads), ratings, verified/company flags; name/shop name/address/agent_id for companies only — private sellers' personal fields are null (filters: source, province, q = company name search, companies, limit)
- GET /api/geo/resolve?q= — Resolve a VN location name (Q7, Tân Thuận, HCM…) or Google Maps URL/short-url → province/district/ward + lat/lng + batdongsan geo mapping (local DB → geocode.maps.co, cached)
- GET /api/geo/forward?address= — Forward geocoding (address → coordinates), Google Geocoding API-compatible. Providers: local DB (0 API calls for 34 provinces + 127 HN districts) → maps.co. Permanently cached. Returns: status, results[{formatted_address, geometry.location, address_components, provider}], api_calls, cached
- GET /api/geo/reverse?latlng=lat,lng — Reverse geocoding (coordinates → address), Google Geocoding API-compatible. Same provider chain, cached at ~1m precision
- GET /api/geo/usage — Provider API call counters since server start (maps.co; goong and here are disabled — no key)
- GET /api/geo/stats?days=7 — Persistent usage analytics: cache hit rate, API calls saved, provider breakdown, top uncached queries
- GET /api/realestate/geo?q= — Resolve a location AND return matching listings in that area
- GET /api/realestate/nearby?lat=&lng=&radius=2 — Listings within radius (km) of a point, sorted by distance. Uses PostgreSQL earthdistance (great-circle). Returns distance_m per listing. Max 50km/500 results.
- GET /api/provinces/summary — Vietnam 2025 province merge (63 → 34 provinces, 3,321 wards, 5 metrics)
- GET /api/geo/vnsdi-provinces — Official VNSDI 34-province boundaries (Resolution 202/2025/QH15, post-merger, WGS84) as a simplified GeoJSON FeatureCollection; the VN-territorial-compliant boundary set behind the maps
- GET /api/provinces/map — Province GeoJSON (official VNSDI boundaries) with merge metadata + metric-based choropleth coloring
- GET /api/provinces/wards — Search merged wards (3,321 total, full-text search, province filter, pagination)
- GET /api/blog — Data-driven blog posts: original cross-source analysis generated from our own crawled metrics (AI-generated posts flagged via ai_generated). ?category= slug, ?limit=
- GET /api/blog/categories — Blog categories (metric domains: daily brief, gold & FX, energy, agriculture, real estate, retail, macro) with post counts
- GET /api/blog/:slug — Single post with markdown body + the cross-source metric snapshot it was built from
- GET /api/mst/:code — Vietnamese company lookup by tax ID (mã số thuế): name, status, address, founded date, tax office. Personal fields (representative, phone) are null except for partner (Unlimited) keys. Cached company_info; ?refresh=true for a live enrich
- GET /api/mst/stats — Aggregate analytics over the 54k+ company corpus: by status (business health — e.g. ~32% registered-but-not-at-address), entity type (DN vs hộ kinh doanh), province, HCMC tax area, formation year, daily enrichment velocity, field coverage. Filters: province (hcm|hanoi|danang|binhduong|dongnai|haiphong|cantho), org (dn|ho), founded_from & founded_to (YYYY-MM-DD founding-date range). Cached 5 min (unfiltered). Dashboard: /mst/thong-ke (date presets: this-year/last-12-month/last-6-month/2015/2014/custom, default 2015)
- GET /blog — Blog index (HTML, Vietnamese). Each post page /blog/:slug carries schema.org BlogPosting + BreadcrumbList JSON-LD and a <link rel="alternate" type="application/json"> to /api/blog/:slug (markdown body + the data snapshot it was written from)
- GET /blog/rss.xml — Blog RSS feed (summary). Also /blog/rss-full.xml (full content:encoded)
- GET /blog/category/:slug/rss.xml — Per-category RSS (and /rss-full.xml variant)

## Endpoints (Pro Plan — quoted in VND on request, 10K calls/day; see https://dulieu.dev/bang-gia)

Pro sells the per-product DATASET. The three grocery aggregate endpoints marked FREE below
(summary, stores) return category/store rollups only and need no API key.

- GET /api/groceries — Grocery prices (56K+ products, COICOP classified, unit pricing). date=latest serves only the newest crawl slice — use /catalog for the full catalog
  Human page: https://dulieu.dev/chi-so-gia — "Chỉ số giá dulieu.dev — thực phẩm & đồ uống": a monthly food & non-alcoholic beverage price index (COICOP 01) from supermarket online shelf prices — matched products, monthly median price, Jevons per class, equal class weights, chain-linked (first month = 100); class table, method and limits (five chains carry ~97 % of matches). Not an official statistic and not a CPI.
- GET /api/groceries/summary — Category averages with COICOP codes. FREE (aggregate only, no product rows)
- GET /api/groceries/stores — Store product counts (6 stores). FREE (aggregate only)
- GET /api/groceries/catalog — Full deduplicated catalog: latest price per product across all crawl dates (not just the latest crawl slice). For sync consumers needing every product at its current price. Filters: store, category, limit (default 200000)
- GET /api/groceries/search?q= — Live product-name search (ILIKE, deduplicated to latest price per product, _raw stripped). For autocomplete / live lookup without syncing the whole catalog. Filters: store, category, limit (default 50)
- GET /api/groceries/freshness — Per-store crawl freshness: catalog_size, latest_date, days_stale, stale flag (≥2 days). Lets consumers detect silent staling
- GET /api/drugs — Drug & pharmacy prices (12K+ products, COICOP 06 classified)
- GET /api/drugs/summary — Drug category averages with drug/Rx counts
- GET /api/drugs/stores — Pharmacy product counts
- GET /api/drugs/catalog — Full deduplicated catalog: latest price per product across all crawl dates. Filters: store, limit (default 200000)
- GET /api/drugs/search?q= — Live drug-name search (ILIKE, deduplicated to latest price per product, _raw stripped). Filters: store, limit (default 50)
- GET /api/mombaby/catalog — Full deduplicated catalog across mom & baby stores. Filters: store, category, limit (default 200000)

## API Key Management (session auth required)

- GET /api/keys — List your API keys
- POST /api/keys — Create a new key (body: {"name": "..."})
- POST /api/keys/:id/rotate — Rotate key (new secret, same ID, stats preserved)
- GET /api/keys/stats — Your usage stats (overview, per-key, top endpoints)
- DELETE /api/keys/:id — Revoke a key

## Admin Endpoints

- GET /api/stats — Global API usage stats (by key, user, endpoint, day)
- GET /api/stats/recent — Recent raw request logs
- GET /api/crawl-logs — Crawler execution history
- GET /api/crawl/progress — Realtime progress of in-flight streaming crawls (live counts: phase, done/total, ok/fail, inserted, pct)

## Query Parameters

All data endpoints accept date filters:
- ?date=2026-05-20 — single date
- ?from=2026-05-01&to=2026-05-20 — date range
- ?previous=7 — last N days
- ?at=2026-05-20 — record-time as-of (per-source): the latest data ≤ that date, with carry-forward fallback so lagged/gappy sources never return empty (also on /api/summary and /api/snapshot)

## Response Format

```json
{
  "source": "dulieu.dev",
  "data": [...],
  "meta": {
    "source": "domain.com",
    "count": 42,
    "updated_at": "2026-05-20T06:00:00.000Z"
  }
}
```

## Rate Limits

- Free: 100 calls/day
- Pro: 10,000 calls/day
- Unlimited: no limits

Price list (VND, VAT stated on the quote): https://dulieu.dev/bang-gia. Free = self-serve API key; Pro and Unlimited = quote by email (info@dulieu.dev). No online checkout.
Business data feeds (SKU-level retail prices, finance series, real-estate aggregates, custom data work), with live coverage per dataset: https://dulieu.dev/du-lieu-doanh-nghiep — quoted in VND by contract. Sample CSVs (facts only, small extract): https://dulieu.dev/public/samples/mau-a-gia-ban-le.csv (retail prices by SKU), https://dulieu.dev/public/samples/mau-b-tai-chinh.csv (FX, gold, deposit rates, fuel).

Headers: X-RateLimit-Plan, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

## Data Sources

Exchange rates: Vietcombank, CafeF (20 currencies)
Gold: DOJI, CafeF, Webgia, VnExpress (SJC, PNJ, branded)
Silver: CafeF (11 domestic types + world)
Interest rates: Webgia, VCB, BIDV, Sacombank, VPBank, CafeF, VnExpress (40+ banks)
Fuel: Webgia, VnExpress
Coffee: Webgia, giacaphe.com, ICE London, ICE NY, B3 Brazil
Pepper: giatieu.com (domestic 5 regions + India Kochi)
Oil: Stooq (WTI, Brent)
Weather: OpenWeatherMap
Indicators: GSO (nso.gov.vn)
Groceries: Lottemart, Cooponline, MM Vietnam, King Food Mart, Bach Hoa Xanh, Sieuthi Go
Drugs: Pharmacity, Long Chau (Nha Thuoc Long Chau)
Electronics: The Gioi Di Dong, CellphoneS, FPT Shop, Hoang Ha Mobile, Di Dong Viet

## Dedicated Pages

- Dashboard: https://dulieu.dev/
- API docs: https://dulieu.dev/api/docs
- Groceries: https://dulieu.dev/groceries
- Drugs: https://dulieu.dev/drugs
- Provinces: https://dulieu.dev/tinh-thanh
- Settings: https://dulieu.dev/settings
- About: https://dulieu.dev/page/about