# 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), 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 15 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 (6 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)
- GET /api/gold — Gold prices (SJC, DOJI, 8+ types)
- GET /api/silver — Silver prices (11 types)
- GET /api/fuel — Fuel prices (6 types, 2 zones)
- GET /api/coffee — Domestic coffee prices (4 regions)
- GET /api/pepper — Pepper prices (domestic 5 regions + international India Kochi)
- GET /api/interest — Bank interest rates (40+ banks, 8 terms)
- GET /api/commodities — All commodity prices (crude oil, coffee futures)
- GET /api/indicators — Economic indicators (CPI, inflation, IIP)
- GET /api/weather — Weather for 70+ cities (all province capitals + tourist destinations)
- GET /api/weather/forecast — 5-day weather forecast for 70+ cities
- 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
- GET /api/geo — Vietnamese administrative geography
- GET /api/plans — Available plans and features
- 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 price per product across all crawl dates (not just the latest crawl slice). 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, province (ho-chi-minh, lam-dong, da-nang, ha-noi, quang-ngai), district, source (guland.vn|batdongsan.com.vn|nhatot.com), date range, limit
- GET /api/realestate/facets — Distinct filter values with counts: provinces (63), property_types, sources (guland/batdongsan/nhatot), transactions (ban/cho-thue). 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 (agencies, brokers, individual sellers; nhatot.com + guland.vn) with active-listing counts (live_ads), ratings, verified/company flags, shop name/address (filters: source, province, q, 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 (geocode.maps.co + goong.io, cached)
- GET /api/realestate/geo?q= — Resolve a location AND return matching listings in that area
- 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, representative, founded date, tax office. 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/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 — $9/mo, 10K calls/day)

- 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
- GET /api/groceries/summary — Category averages with COICOP codes
- GET /api/groceries/stores — Store product counts (6 stores)
- 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 (contact us)

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
- Banks: https://dulieu.dev/banks
- Provinces: https://dulieu.dev/tinh-thanh
- Settings: https://dulieu.dev/settings
- About: https://dulieu.dev/page/about