ExploreDocsBlog

Search cities

Search the world's cities (~34k populated places over 15k people, plus capitals, from GeoNames), ordered by population. Filter by name (`q`) and/or country. Also available: `GET /cities/{geonameId}` for one city, and `GET /cities/near?lat=&lng=` for the nearest cities to a coordinate.

GET
/cities

Search the world's cities (~34k populated places over 15k people, plus capitals, from GeoNames), ordered by population. Filter by name (q) and/or country. Also available: GET /cities/{geonameId} for one city, and GET /cities/near?lat=&lng= for the nearest cities to a coordinate.

Query Parameters

q?string

Match cities whose name contains this text.

country?string

ISO 3166-1 alpha-2 country code to filter by.

limit?integer

Max results (1–100, default 20).

Response Body

application/json

text/plain

curl -X GET "https://example.com/cities?q=paris&country=FR&limit=20"
[  {    "geonameId": 2988507,    "name": "Paris",    "asciiName": "Paris",    "countryCode": "FR",    "admin1Code": "string",    "latitude": 48.85341,    "longitude": 2.3488,    "population": 2138551,    "timezone": "Europe/Paris",    "featureCode": "PPLC"  }]
"Country not found"

Geolocate an IP address GET

Returns the country for an IP address (IPv4 or IPv6), enriched with the full country record. Omit the IP (`GET /ip`) to geolocate the caller's own IP. A batch lookup of up to 100 IPs is available via `POST /ip` with a JSON array body. `GET /ip/info` returns metadata about the geolocation data source (provider, license, last updated).

Search all places GET

Search the full GeoNames gazetteer — ~12M features worldwide (cities, towns, mountains, rivers, regions and more), ordered by population. Filter by name (`q`), `country`, and feature `class`. Also: `GET /places/{geonameId}` for one place and `GET /places/near?lat=&lng=` for the nearest features to a coordinate.