Tìm thành phố thế giới API
Gợi ý 70.000 thành phố thế giới theo tên (gõ không dấu được, có tên tiếng Anh và tiếng Việt), tìm thành phố gần một toạ độ, xem dân số và múi giờ.
q tìm tên thành phố theo tiền tố, không phân biệt dấu và chữ hoa (ha noi, Hà Nội hay hanoi đều ra Hà Nội), gồm cả tên tiếng Anh và tiếng Việt mà GeoNames có (Thượng Hải ra Shanghai). Trùng khớp hoàn toàn được xếp trước, rồi đến khớp tiền tố, rồi đến tên có một từ phía sau bắt đầu bằng chuỗi bạn gõ (york cũng ra New York); trong mỗi nhóm thành phố đông dân hơn đứng trước. Lọc bằng country (mã ISO) và min_population.
lat + lon trả về các thành phố gần nhất (reverse geocode mức thành phố) kèm khoảng cách km, có thể giới hạn bằng radius_km. id (hoặc /v1/cities/<geonameid>) trả về một thành phố với quốc gia, đơn vị hành chính cấp 1 (bang / tỉnh), dân số, độ cao, múi giờ IANA và độ lệch UTC hiện tại, loại địa danh (thủ đô, thủ phủ…) và các tên khác; details=true thêm các trường này vào kết quả tìm kiếm.
Dữ liệu: GeoNames cities5000 (mọi điểm dân cư từ 5.000 người trở lên và trụ sở các đơn vị hành chính), cập nhật hàng tuần, giấy phép CC BY 4.0 – khi hiển thị dữ liệu hãy giữ dòng ghi công trong trường attribution. Tên đơn vị hành chính theo GeoNames, có thể chưa cập nhật các đợt sắp xếp mới (tỉnh thành Việt Nam sau 2025 xem /v1/vn-provinces).
Tham số
| Tên | Vị trí | Kiểu | Bắt buộc | Mặc định | |
|---|---|---|---|---|---|
q | query | string | không | Tên hoặc phần đầu của tên (không cần dấu). Bắt buộc một trong q, lat+lon hoặc id. | |
lat | query | number | không | Vĩ độ để tìm thành phố gần nhất (cùng lon). | |
lon | query | number | không | Kinh độ (chấp nhận lng). | |
id | query | string | không | Mã GeoNames để xem chi tiết một thành phố (hoặc /v1/cities/<id>). | |
country | query | string | không | Lọc theo mã quốc gia ISO 3166-1 alpha-2, ví dụ VN. | |
min_population | query | number | không | Chỉ lấy thành phố có dân số từ mức này. | |
radius_km | query | number | không | Khoảng cách tối đa khi tìm gần nhất. | |
limit | query | number | không | 10 | Số kết quả (1–50). |
details | query | boolean | không | false | Trả đủ chi tiết (admin1, độ lệch múi giờ, độ cao, tên khác) trong kết quả tìm kiếm. |
Ví dụ
curl "https://apibox.io.vn/v1/cities?q=da%20nang&limit=2" \
-H "Authorization: Bearer YOUR_API_KEY"const res = await fetch('https://apibox.io.vn/v1/cities?q=da%20nang&limit=2', {
method: 'GET',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
},
});
const data = await res.json();
console.log(data);import requests
res = requests.get(
"https://apibox.io.vn/v1/cities?q=da%20nang&limit=2",
headers={"Authorization": "Bearer YOUR_API_KEY"},
timeout=30,
)
print(res.json())<?php
$ch = curl_init('https://apibox.io.vn/v1/cities?q=da%20nang&limit=2');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));Kết quả trả về
{
"query": {
"q": "da nang",
"country": null,
"min_population": null
},
"count": 1,
"total_matches": 1,
"results": [
{
"id": 1583992,
"name": "Da Nang",
"name_en": "Da Nang",
"name_vi": "Đà Nẵng",
"country_code": "VN",
"country": "Vietnam",
"admin1": "Da Nang City",
"lat": 16.0678,
"lon": 108.2208,
"population": 1276000,
"timezone": "Asia/Ho_Chi_Minh",
"match": "exact"
}
],
"attribution": "Data © GeoNames (www.geonames.org), CC BY 4.0",
"data_version": "2026-11-11",
"dataset": "GeoNames cities5000: 70026 places with >= 5 000 inhabitants or seats of administrative divisions"
}
Ứng dụng
- Gợi ý thành phố trong form đăng ký hoặc thanh toán quốc tế
- Hiển thị thành phố gần nhất từ toạ độ GPS của ảnh hay thiết bị
- Lấy múi giờ theo thành phố của khách để hẹn lịch gọi
- Đưa danh sách thành phố có tên tiếng Anh và tiếng Việt vào app du lịch
Hỏi đáp
Có cần gõ dấu không?
Không. Tên được so khớp bỏ dấu và không phân biệt hoa thường, nên "da nang" ra Đà Nẵng và "sao paulo" ra São Paulo.
Vì sao không thấy một thị trấn nhỏ?
Bộ dữ liệu chỉ giữ điểm dân cư từ 5.000 người và trụ sở các đơn vị hành chính (khoảng 70.000 địa danh), không có làng xã nhỏ.
Cần ghi công thế nào?
Ghi công GeoNames theo CC BY 4.0: hiển thị chuỗi attribution mà API trả về (ví dụ ở chân trang có dùng dữ liệu).
API liên quan
Kiểm tra JSON
Kiểm tra cú pháp JSON, báo đúng dòng và cột bị lỗi, và validate dữ liệu theo JSON Schema (draft 4, 7, 2019-09 hoặc 2020-12).
{ }Định dạng JSON
Làm đẹp JSON với thụt lề 0-8 dấu cách hoặc tab, rút gọn (minify) hoặc sắp xếp key theo bảng chữ cái. Báo lỗi cú pháp kèm dòng và cột.
CSVCSV sang JSON
Chuyển CSV thành mảng object JSON theo dòng tiêu đề, tự nhận dấu phân cách, tự chuyển số và boolean, báo lỗi từng dòng.