World City Search API

Autocomplete 70 000 world cities by name (accents optional, English and Vietnamese names), find the nearest cities to a point, population and time zone.

GEThttps://apibox.io.vn/v1/cities

Data & JSON▶ Try it online

q searches city names by prefix, without caring about accents or case (ha noi, Hà Nội and hanoi all find Hanoi), including the English and Vietnamese names GeoNames has (Thượng Hải finds Shanghai). Exact names come first, then prefixes, then names where a later word starts with your text (york also matches New York); within each group the bigger city wins. Filter with country (ISO code) and min_population.

lat + lon returns the nearest cities (reverse geocoding at city level) with the distance in km, optionally within radius_km. id (or /v1/cities/<geonameid>) returns one city with its country, first-level division (state / province), population, elevation, IANA time zone and current UTC offset, feature type (capital, seat of a division…) and alternate names; details=true adds the same fields to search results.

Data: GeoNames cities5000 (every place with at least 5 000 inhabitants plus seats of administrative divisions), refreshed weekly, licensed CC BY 4.0 – keep the attribution text visible when you show the data. Division names follow GeoNames and may lag behind recent reorganisations (for Vietnam's 2025 provinces use /v1/vn-provinces).

Parameters

Name	In	Type	Required	Default
`q`	query	string	no		Name or beginning of a name (accents optional). One of `q`, `lat`+`lon` or `id` is required.
`lat`	query	number	no		Latitude for a nearest-city search (with `lon`).
`lon`	query	number	no		Longitude (`lng` accepted).
`id`	query	string	no		GeoNames id for the details of one city (also `/v1/cities/<id>`).
`country`	query	string	no		ISO 3166-1 alpha-2 filter, e.g. `VN`.
`min_population`	query	number	no		Only cities with at least this population.
`radius_km`	query	number	no		Maximum distance for a nearest search.
`limit`	query	number	no	`10`	Results (1–50).
`details`	query	boolean	no	`false`	Full details (admin1, time zone offset, elevation, alternate names) in search results.

Example

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));

Response

{
  "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"
}

Use cases

City autocomplete in an international sign-up or checkout form
Show the nearest city for GPS coordinates of a photo or a device
Get the time zone of a customer's city to schedule calls
Populate a travel app with city names in English and Vietnamese

FAQ

Do I need to type accents?

No. Names are matched without accents and case, so "da nang" finds Đà Nẵng and "sao paulo" finds São Paulo.

Why is a small town missing?

The dataset keeps places with at least 5 000 inhabitants and seats of administrative divisions (about 70 000 places). Villages are not included.

What must I credit?

GeoNames, under CC BY 4.0: show the attribution string returned by the API (for example in the footer of the page that displays the results).

Related APIs

{✓}

World City Search API

Parameters

Example

Response

Use cases

FAQ

Related APIs

JSON Validator

JSON Formatter

CSV to JSON