🏥 Hanoi Clinics API

API cộng đồng mở về danh sách phòng khám tại Hà Nội — miễn phí, không cần xác thực.

Dữ liệu do cộng đồng đóng góp và thu thập từ OpenStreetMap. Mọi người đều có thể thêm/sửa thông tin qua Pull Request.

🚀 Base URL

https://hanoi-clinics-api.vercel.app/api

📡 Endpoints

Method	Endpoint	Mô tả
GET	/clinics	Lấy toàn bộ danh sách phòng khám
GET	/clinics?district=dong_da	Lọc theo quận/huyện
GET	/clinics?type=da_khoa	Lọc theo loại phòng khám
GET	/clinics?lat=21.02&lng=105.85&radius=5	Tìm phòng khám gần vị trí
GET	/clinics/{id}	Lấy chi tiết một phòng khám
GET	/clinics/nearby	Tìm phòng khám gần (với distance)
GET	/clinics/types	Danh sách loại phòng khám
POST	/clinics/validate	Validate dữ liệu trước khi contribute
GET	/districts	Danh sách quận/huyện
GET	/health	Health check endpoint

📦 Ví dụ Response

{
  "success": true,
  "total": 2,
  "data": [
    {
      "id": 1,
      "name": "Phòng khám Đa khoa Hưng Thịnh",
      "address": "380 Xã Đàn, Đống Đa, Hà Nội",
      "district": "dong_da",
      "phone": "024-3852-3852",
      "type": "da_khoa",
      "coordinates": {
        "lat": 21.0245,
        "lng": 105.8412
      },
      "data_source": "osm",
      "last_updated": "2026-03-31T00:00:00.000Z"
    }
  ]
}

🔍 Tìm kiếm gần đây (Nearby Search)

GET /api/clinics/nearby?lat=21.0245&lng=105.8412&radius=5

Response bao gồm khoảng cách đến mỗi phòng khám:

{
  "success": true,
  "total": 3,
  "center": { "lat": 21.0245, "lng": 105.8412 },
  "radius_km": 5,
  "data": [
    {
      "id": 1,
      "name": "Phòng khám Đa khoa Hưng Thịnh",
      "distance": 0.12,
      ...
    }
  ]
}

🤝 Đóng góp dữ liệu

Cách 1: Thủ công

1. Fork repo này
2. Thêm/sửa dữ liệu trong data/clinics.json
3. Tạo Pull Request với mô tả rõ ràng

Cách 2: Thu thập tự động từ OSM

npm run collect-osm

Lưu ý về dữ liệu OSM: Dữ liệu từ OpenStreetMap sử dụng license CC-BY-SA. Khi contribute dữ liệu OSM, vui lòng ghi nhận nguồn.

Xem hướng dẫn chi tiết tại CONTRIBUTING.md

🛠 Chạy local

# Cài đặt
npm install

# Chạy dev server
npm run dev

# Server chạy tại http://localhost:3000

# Chạy tests
npm test

# Thu thập dữ liệu từ OSM
npm run collect-osm

📁 Cấu trúc dự án

hanoi-clinics-api/
├── api/
│   ├── index.js              # Main entry
│   ├── routes/clinics.js     # Clinic routes
│   ├── middleware/
│   │   ├── errorHandler.js    # Error handling
│   │   └── validator.js       # Input validation
│   └── utils/geo.js           # Geolocation helpers
├── data/
│   ├── clinics.json           # Clinic data
│   └── districts.json         # District definitions
├── scripts/
│   └── collect-osm-data.js    # OSM data collector
├── tests/
│   └── api.test.js            # API tests
└── package.json

🔒 Validation

API có validation nghiêm ngặt cho input:

• District phải thuộc danh sách hợp lệ
• Type phải thuộc danh sách hợp lệ
• Coordinates phải trong phạm vi hợp lệ (-90/90 lat, -180/180 lng)
• Phone number phải đúng format

📄 License

MIT License — tự do sử dụng, chia sẻ và phát triển.