01Xác thực
API bảo vệ bằng Bearer token. Đặt token qua biến môi trường API_TOKEN khi chạy server, rồi gửi kèm mỗi request.
# Chạy server có token API_TOKEN=your-secret-key npm start
Mỗi request phải kèm header:
Authorization: Bearer your-secret-key
# Ví dụ với curl curl -H "Authorization: Bearer your-secret-key" \ https://geo.empatydev.net/countries # Ví dụ với fetch (JavaScript) fetch("https://geo.empatydev.net/countries", { headers: { "Authorization": "Bearer your-secret-key" } })
API_TOKEN, server chạy chế độ mở (dev) — không yêu cầu token.02Quốc gia
Danh sách quốc gia và chi tiết một quốc gia (kèm múi giờ, bản dịch tên).
Danh sách tất cả quốc gia (thông tin cơ bản, ~5KB).
Chi tiết đầy đủ một quốc gia: cờ, tiền tệ, vùng, múi giờ, bản dịch.
# Chi tiết nước Mỹ curl https://geo.empatydev.net/countries/US # Kết quả (rút gọn) { "name": "United States", "iso2": "US", "currency": "USD", "capital": "Washington", "emoji": "🇺🇸" }
03Tỉnh / Bang
Các tỉnh/bang trong một quốc gia, hoặc chi tiết một tỉnh cụ thể.
Tất cả tỉnh/bang của quốc gia.
Chi tiết một tỉnh/bang theo mã.
# Bang California của Mỹ
curl https://geo.empatydev.net/state/US/CA
04Thành phố
Thành phố theo tỉnh, theo quốc gia, hoặc toàn cầu.
Tất cả thành phố trong một tỉnh/bang. Khuyến nghị dùng route này.
Tất cả thành phố của một quốc gia.
⚠ Dữ liệu lớn — dùng thận trọng
Mọi thành phố trên thế giới.
⚠ 8MB+ — hiếm khi cần
# Thành phố trong bang CA của Mỹ curl https://geo.empatydev.net/cities/US/CA # Thành phố của Singapore (tỉnh mã "01") curl https://geo.empatydev.net/cities/SG/01
05Tìm kiếm
Tìm thành phố theo tên (khớp một phần, không phân biệt hoa thường) trong phạm vi một tỉnh/bang.
Bắt buộc có ?q=. Thiếu → trả về 400.
# Tìm "San" trong bang California curl "https://geo.empatydev.net/search/cities/US/CA?q=San"
q phải mã hoá URL: ?q=Los%20Angeles.06Tên nhanh
Lấy tên từ mã — nhẹ hơn khi chỉ cần tên hiển thị.
Tên quốc gia, ví dụ "Japan".
Tên tỉnh/bang, ví dụ "Texas".
07Múi giờ
Múi giờ của cả quốc gia, hoặc của một thành phố cụ thể.
Mảng tên múi giờ của quốc gia.
Bắt buộc có ?city=. Tên phải khớp đúng với dữ liệu thành phố.
# Múi giờ của Los Angeles curl "https://geo.empatydev.net/timezone/city/US/CA?city=Los%20Angeles" # "America/Los_Angeles"
08Kiểm tra hợp lệ
Kiểm tra mã có tồn tại không. Luôn trả 200 với { "valid": true|false }.
Mã quốc gia có tồn tại?
Mã tỉnh/bang có tồn tại trong quốc gia đó?
curl https://geo.empatydev.net/valid/country/US # {"valid":true} curl https://geo.empatydev.net/valid/state/US/ZZ # {"valid":false}
09Mã lỗi
Lỗi trả về JSON dạng { "error": "..." }.
| Mã | Ý nghĩa | Khi nào |
|---|---|---|
| 200 | OK | Có dữ liệu trả về |
| 400 | Bad Request | Thiếu ?q= hoặc ?city= |
| 401 | Unauthorized | Thiếu hoặc sai Bearer token |
| 404 | Not Found | Không tìm thấy dữ liệu / route sai |
| 500 | Server Error | Lỗi nội bộ khi xử lý |
10Bảng tra nhanh
Toàn bộ 14 route trong một bảng.
| Route | Trả về |
|---|---|
| GET /countries | Danh sách quốc gia |
| GET /countries/:cc | Chi tiết một quốc gia |
| GET /state/:cc | Tỉnh/bang của quốc gia |
| GET /state/:cc/:sc | Chi tiết một tỉnh/bang |
| GET /cities/:cc/:sc | Thành phố trong tỉnh/bang |
| GET /cities/:cc | Thành phố cả quốc gia ⚠ |
| GET /cities | Mọi thành phố (8MB+) ⚠ |
| GET /search/cities/:cc/:sc?q= | Tìm thành phố theo tên |
| GET /name/country/:cc | Tên quốc gia |
| GET /name/state/:cc/:sc | Tên tỉnh/bang |
| GET /timezones/:cc | Múi giờ của quốc gia |
| GET /timezone/city/:cc/:sc?city= | Múi giờ một thành phố |
| GET /valid/country/:cc | Kiểm tra mã quốc gia |
| GET /valid/state/:cc/:sc | Kiểm tra mã tỉnh/bang |