Skip to main content

World Cities API

REAL DATA

6,300+ world cities from a pinned GeoNames snapshot: coordinates, IANA timezone, population and capital flag — filter by country, size, name or distance.

Authoritative reference data or standards computation

Base URL
/api/cities
Category
Geo & Reference
Capabilities
2 routes
Last updated
July 30, 2026
Data sources · 3

GET /api/cities List world cities (filter by country, size, name or capital status)

Returns matching places from the pinned GeoNames snapshot, ordered by population or name. A page holds at most 100 records; use offset to walk further.

Live requestRuns against the public API
No key required
GET/api/cities?count=10

Request parameters

Only cities in this country (ISO 3166-1 alpha-2, case-insensitive — dk and DK both work). A valid two-letter code with no cities in the set returns an empty list; anything that isn't two letters is a 400.

Only cities whose name or GeoNames ASCII alias contains this text — case-, diacritic- and apostrophe-insensitive (sao matches São Paulo, xian matches Xi’an).

Only cities whose GeoNames population is ≥ this value. Places with no published population are excluded, since an unknown figure cannot be shown to clear the bar.

true = only places GeoNames codes PPLC (national capitals); false = only non-capitals; omit for both.

population = largest first, unknown populations last; name = A→Z (diacritic-insensitive).

Skip this many matches before count is applied, so you can page through large results (offset=100 with count=100 returns the second hundred).

Advanced response options6 options

Limit the number of returned records (1–100). Defaults to 25.

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Response format: json envelope, ndjson (one record per line) or csv.

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/cities?count=10"
const res = await fetch("https://randomapi.dev/api/cities?count=10");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/cities?count=10").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/cities?count=10"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 6
country string

Only cities in this country (ISO 3166-1 alpha-2, case-insensitive — dk and DK both work). A valid two-letter code with no cities in the set returns an empty list; anything that isn't two letters is a 400.

example: country=DK
search string

Only cities whose name or GeoNames ASCII alias contains this text — case-, diacritic- and apostrophe-insensitive (sao matches São Paulo, xian matches Xi’an).

example: search=york
minPopulation int

Only cities whose GeoNames population is ≥ this value. Places with no published population are excluded, since an unknown figure cannot be shown to clear the bar.

allowed: ≥ 0
example: minPopulation=1000000
capital boolean

true = only places GeoNames codes PPLC (national capitals); false = only non-capitals; omit for both.

example: capital=true
sort enum

population = largest first, unknown populations last; name = A→Z (diacritic-insensitive).

default: population
allowed: population | name
example: sort=name
offset int

Skip this many matches before count is applied, so you can page through large results (offset=100 with count=100 returns the second hundred).

default: 0
allowed: 0 – 100000
example: offset=100
Universal parameters Shared response and formatting options 6
count int

Limit the number of returned records (1–100). Defaults to 25.

default: 25
allowed: 1 – 100
example: count=3
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=name,asciiName
exclude list

Return all fields except these (comma-separated).

example: exclude=isCapital
format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 10
name string

GeoNames place name — the common international form, diacritics included.

example: Copenhagen

asciiName string

The same name transliterated to plain ASCII by GeoNames (São Paulo → Sao Paulo). Equal to name when it is already ASCII.

example: Copenhagen

country string

English country name, joined from the ISO 3166-1 country dataset.

example: Denmark

countryCode string

ISO 3166-1 alpha-2 country code.

example: DK

admin1 string nullable

First-order administrative division (state, province, region…) in GeoNames' ASCII spelling; null where GeoNames publishes no first-order division for the place.

example: Capital Region

latitude float

GeoNames point latitude (WGS84, 4 decimals).

example: 55.6759

longitude float

GeoNames point longitude (WGS84, 4 decimals).

example: 12.5655

timezone string (IANA)

The IANA timezone identifier GeoNames records for the place.

example: Europe/Copenhagen

population integer nullable

GeoNames population figure — an APPROXIMATE administrative/city-proper count of mixed vintage, not a metropolitan total and not a census value. null when GeoNames publishes no figure.

example: 1153615

isCapital boolean

True when GeoNames codes the place PPLC (capital of a political entity). GeoNames marks at most one capital per country.

example: true

Documented examples

Build-generated requests and complete responses 7
The 10 most populous places in the set
GET /api/cities?count=10 
{
  "data": [
    {
      "name": "Shanghai",
      "asciiName": "Shanghai",
      "country": "China",
      "countryCode": "CN",
      "admin1": "Shanghai",
      "latitude": 31.2222,
      "longitude": 121.4581,
      "timezone": "Asia/Shanghai",
      "population": 24874500,
      "isCapital": false
    },
    {
      "name": "Beijing",
      "asciiName": "Beijing",
      "country": "China",
      "countryCode": "CN",
      "admin1": "Beijing",
      "latitude": 39.9075,
      "longitude": 116.3972,
      "timezone": "Asia/Shanghai",
      "population": 18960744,
      "isCapital": true
    },
    {
      "name": "Shenzhen",
      "asciiName": "Shenzhen",
      "country": "China",
      "countryCode": "CN",
      "admin1": "Guangdong",
      "latitude": 22.5455,
      "longitude": 114.0683,
      "timezone": "Asia/Shanghai",
      "population": 17494398,
      "isCapital": false
    },
    {
      "name": "Guangzhou",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}
Every Danish city in the snapshot
GET /api/cities?country=dk&count=100 
{
  "data": [
    {
      "name": "Copenhagen",
      "asciiName": "Copenhagen",
      "country": "Denmark",
      "countryCode": "DK",
      "admin1": "Capital Region",
      "latitude": 55.6759,
      "longitude": 12.5655,
      "timezone": "Europe/Copenhagen",
      "population": 1153615,
      "isCapital": true
    },
    {
      "name": "Århus",
      "asciiName": "Arhus",
      "country": "Denmark",
      "countryCode": "DK",
      "admin1": "Central Jutland",
      "latitude": 56.1567,
      "longitude": 10.2108,
      "timezone": "Europe/Copenhagen",
      "population": 285273,
      "isCapital": false
    },
    {
      "name": "Odense",
      "asciiName": "Odense",
      "country": "Denmark",
      "countryCode": "DK",
      "admin1": "South Denmark",
      "latitude": 55.3959,
      "longitude": 10.3883,
      "timezone": "Europe/Copenhagen",
      "population": 180863,
      "isCapital": false
    },
    {
      "name": "Aalborg",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}
German cities above one million
GET /api/cities?country=de&minPopulation=1000000 
{
  "data": [
    {
      "name": "Berlin",
      "asciiName": "Berlin",
      "country": "Germany",
      "countryCode": "DE",
      "admin1": "State of Berlin",
      "latitude": 52.5244,
      "longitude": 13.4105,
      "timezone": "Europe/Berlin",
      "population": 3426354,
      "isCapital": true
    },
    {
      "name": "Hamburg",
      "asciiName": "Hamburg",
      "country": "Germany",
      "countryCode": "DE",
      "admin1": "Hamburg",
      "latitude": 53.5507,
      "longitude": 9.993,
      "timezone": "Europe/Berlin",
      "population": 1973896,
      "isCapital": false
    },
    {
      "name": "Munich",
      "asciiName": "Munich",
      "country": "Germany",
      "countryCode": "DE",
      "admin1": "Bavaria",
      "latitude": 48.1374,
      "longitude": 11.5755,
      "timezone": "Europe/Berlin",
      "population": 1505005,
      "isCapital": false
    },
    {
      "name": "Köln",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}
National capitals, alphabetically
GET /api/cities?capital=true&sort=name&count=100 
{
  "data": [
    {
      "name": "Abu Dhabi",
      "asciiName": "Abu Dhabi",
      "country": "United Arab Emirates",
      "countryCode": "AE",
      "admin1": "Abu Dhabi",
      "latitude": 24.4512,
      "longitude": 54.397,
      "timezone": "Asia/Dubai",
      "population": 1807000,
      "isCapital": true
    },
    {
      "name": "Abuja",
      "asciiName": "Abuja",
      "country": "Nigeria",
      "countryCode": "NG",
      "admin1": "FCT",
      "latitude": 9.0579,
      "longitude": 7.4951,
      "timezone": "Africa/Lagos",
      "population": 2690000,
      "isCapital": true
    },
    {
      "name": "Accra",
      "asciiName": "Accra",
      "country": "Ghana",
      "countryCode": "GH",
      "admin1": "Greater Accra",
      "latitude": 5.556,
      "longitude": -0.1969,
      "timezone": "Africa/Accra",
      "population": 1963264,
      "isCapital": true
    },
    {
      "name": "Adamstown",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}
Find São Paulo without typing diacritics
GET /api/cities?search=sao+paulo 
{
  "data": [
    {
      "name": "São Paulo",
      "asciiName": "Sao Paulo",
      "country": "Brazil",
      "countryCode": "BR",
      "admin1": "São Paulo",
      "latitude": -23.5475,
      "longitude": -46.6361,
      "timezone": "America/Sao_Paulo",
      "population": 12400232,
      "isCapital": false
    }
  ],
  "meta": {
    "endpoint": "cities",
    "count": 1,
    "params": {
      "search": "sao paulo",
      "sort": "population",
      "offset": 0
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}
The second hundred US places by population
GET /api/cities?country=us&count=100&offset=100 
{
  "data": [
    {
      "name": "Irving",
      "asciiName": "Irving",
      "country": "United States",
      "countryCode": "US",
      "admin1": "Texas",
      "latitude": 32.814,
      "longitude": -96.9489,
      "timezone": "America/Chicago",
      "population": 236607,
      "isCapital": false
    },
    {
      "name": "Boise",
      "asciiName": "Boise",
      "country": "United States",
      "countryCode": "US",
      "admin1": "Idaho",
      "latitude": 43.6135,
      "longitude": -116.2035,
      "timezone": "America/Boise",
      "population": 235684,
      "isCapital": false
    },
    {
      "name": "Chesapeake",
      "asciiName": "Chesapeake",
      "country": "United States",
      "countryCode": "US",
      "admin1": "Virginia",
      "latitude": 36.819,
      "longitude": -76.2749,
      "timezone": "America/New_York",
      "population": 235429,
      "isCapital": false
    },
    {
      "name": "North Las Vegas",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}
Name + timezone reference table
GET /api/cities?sort=name&count=100&fields=name,countryCode,timezone 
{
  "data": [
    {
      "name": "6th of October City",
      "countryCode": "EG",
      "timezone": "Africa/Cairo"
    },
    {
      "name": "A Coruña",
      "countryCode": "ES",
      "timezone": "Europe/Madrid"
    },
    {
      "name": "Aachen",
      "countryCode": "DE",
      "timezone": "Europe/Berlin"
    },
    {
      "name": "Aalborg",
      "countryCode": "DK",
      "timezone": "Europe/Copenhagen"
    },
    {
      "name": "Aasiaat",
      "countryCode": "GL",
      "timezone": "America/Nuuk"
    },
    {
      "name": "Aba",
      "countryCode": "NG",
      "timezone": "Africa/Lagos"
    },
    {
      "name": "Abadan",
      "countryCode": "IR",
      "timezone": "Asia/Tehran"
    },
    {
      "name": "Abaetetuba",
      "countryCode": "BR",
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

GET /api/cities/nearest Find the nearest cities to a coordinate

Ranks the pinned GeoNames snapshot by spherical great-circle distance from each place's point coordinate. Optional country, size and radius filters apply before count.

Live requestRuns against the public API
No key required
GET/api/cities/nearest?lat=48.8566&lng=2.3522&maxDistanceKm=100&count=100

Request parameters

Search-point latitude in WGS84 decimal degrees (-90 to 90).

Search-point longitude in WGS84 decimal degrees (-180 to 180).

Optional maximum spherical great-circle distance in kilometers. Omit it to rank the whole snapshot before count is applied.

Optional ISO 3166-1 alpha-2 country filter, case-insensitive. It filters only cities present in this snapshot.

Optional floor on the GeoNames population, so you can ask for the nearest sizeable city rather than the nearest village. Places with no published figure are excluded.

Advanced response options6 options

Limit the number of returned records (1–100). Defaults to 10.

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Response format: json envelope, ndjson (one record per line) or csv.

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/cities/nearest?lat=48.8566&lng=2.3522&maxDistanceKm=100&count=100"
const res = await fetch("https://randomapi.dev/api/cities/nearest?lat=48.8566&lng=2.3522&maxDistanceKm=100&count=100");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/cities/nearest?lat=48.8566&lng=2.3522&maxDistanceKm=100&count=100").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/cities/nearest?lat=48.8566&lng=2.3522&maxDistanceKm=100&count=100"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 5
lat float required

Search-point latitude in WGS84 decimal degrees (-90 to 90).

allowed: -90 – 90
example: lat=48.8566
lng float required

Search-point longitude in WGS84 decimal degrees (-180 to 180).

allowed: -180 – 180
example: lng=2.3522
maxDistanceKm float

Optional maximum spherical great-circle distance in kilometers. Omit it to rank the whole snapshot before count is applied.

allowed: 0 – 20020
example: maxDistanceKm=100
country string

Optional ISO 3166-1 alpha-2 country filter, case-insensitive. It filters only cities present in this snapshot.

example: country=DK
minPopulation int

Optional floor on the GeoNames population, so you can ask for the nearest sizeable city rather than the nearest village. Places with no published figure are excluded.

allowed: ≥ 0
example: minPopulation=500000
Universal parameters Shared response and formatting options 6
count int

Limit the number of returned records (1–100). Defaults to 10.

default: 10
allowed: 1 – 100
example: count=3
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=name,asciiName
exclude list

Return all fields except these (comma-separated).

example: exclude=distanceKm
format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 11
name string

GeoNames place name — the common international form, diacritics included.

example: Copenhagen

asciiName string

The same name transliterated to plain ASCII by GeoNames (São Paulo → Sao Paulo). Equal to name when it is already ASCII.

example: Copenhagen

country string

English country name, joined from the ISO 3166-1 country dataset.

example: Denmark

countryCode string

ISO 3166-1 alpha-2 country code.

example: DK

admin1 string nullable

First-order administrative division (state, province, region…) in GeoNames' ASCII spelling; null where GeoNames publishes no first-order division for the place.

example: Capital Region

latitude float

GeoNames point latitude (WGS84, 4 decimals).

example: 55.6759

longitude float

GeoNames point longitude (WGS84, 4 decimals).

example: 12.5655

timezone string (IANA)

The IANA timezone identifier GeoNames records for the place.

example: Europe/Copenhagen

population integer nullable

GeoNames population figure — an APPROXIMATE administrative/city-proper count of mixed vintage, not a metropolitan total and not a census value. null when GeoNames publishes no figure.

example: 1153615

isCapital boolean

True when GeoNames codes the place PPLC (capital of a political entity). GeoNames marks at most one capital per country.

example: true

distanceKm float

Spherical great-circle distance to the GeoNames point coordinate, using the IUGG mean Earth radius; rounded to 3 decimals.

example: 0

Documented examples

Build-generated requests and complete responses 4
Cities within 100 km of Paris
GET /api/cities/nearest?lat=48.8566&lng=2.3522&maxDistanceKm=100&count=100 
{
  "data": [
    {
      "name": "Paris",
      "asciiName": "Paris",
      "country": "France",
      "countryCode": "FR",
      "admin1": "Île-de-France",
      "latitude": 48.8534,
      "longitude": 2.3488,
      "timezone": "Europe/Paris",
      "population": 2138551,
      "isCapital": true,
      "distanceKm": 0.434
    },
    {
      "name": "Paris 11 Popincourt",
      "asciiName": "Paris 11 Popincourt",
      "country": "France",
      "countryCode": "FR",
      "admin1": "Île-de-France",
      "latitude": 48.8574,
      "longitude": 2.3795,
      "timezone": "Europe/Paris",
      "population": 138170,
      "isCapital": false,
      "distanceKm": 1.999
    },
    {
      "name": "Paris 13 Gobelins",
      "asciiName": "Paris 13 Gobelins",
      "country": "France",
      "countryCode": "FR",
      "admin1": "Île-de-France",
      "latitude": 48.8322,
      "longitude": 2.3561,
      "timezone": "Europe/Paris",
      "population": 181271,
      "isCapital": false,
      "distanceKm": 2.728
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}
Nearest half-million-plus city to Zurich
GET /api/cities/nearest?lat=47.3769&lng=8.5417&minPopulation=500000&count=5 
{
  "data": [
    {
      "name": "Stuttgart",
      "asciiName": "Stuttgart",
      "country": "Germany",
      "countryCode": "DE",
      "admin1": "Baden-Wurttemberg",
      "latitude": 48.7823,
      "longitude": 9.177,
      "timezone": "Europe/Berlin",
      "population": 612663,
      "isCapital": false,
      "distanceKm": 163.243
    },
    {
      "name": "Milan",
      "asciiName": "Milan",
      "country": "Italy",
      "countryCode": "IT",
      "admin1": "Lombardy",
      "latitude": 45.4643,
      "longitude": 9.1895,
      "timezone": "Europe/Rome",
      "population": 1371498,
      "isCapital": false,
      "distanceKm": 218.39
    },
    {
      "name": "Munich",
      "asciiName": "Munich",
      "country": "Germany",
      "countryCode": "DE",
      "admin1": "Bavaria",
      "latitude": 48.1374,
      "longitude": 11.5755,
      "timezone": "Europe/Berlin",
      "population": 1505005,
      "isCapital": false,
      "distanceKm": 242.02
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}
US cities within 200 km of New York
GET /api/cities/nearest?lat=40.7128&lng=-74.006&country=US&maxDistanceKm=200&count=100 
{
  "data": [
    {
      "name": "New York City",
      "asciiName": "New York City",
      "country": "United States",
      "countryCode": "US",
      "admin1": "New York",
      "latitude": 40.7143,
      "longitude": -74.006,
      "timezone": "America/New_York",
      "population": 8804190,
      "isCapital": false,
      "distanceKm": 0.167
    },
    {
      "name": "Jersey City",
      "asciiName": "Jersey City",
      "country": "United States",
      "countryCode": "US",
      "admin1": "New Jersey",
      "latitude": 40.7282,
      "longitude": -74.0776,
      "timezone": "America/New_York",
      "population": 264290,
      "isCapital": false,
      "distanceKm": 6.272
    },
    {
      "name": "Brooklyn",
      "asciiName": "Brooklyn",
      "country": "United States",
      "countryCode": "US",
      "admin1": "New York",
      "latitude": 40.6501,
      "longitude": -73.9496,
      "timezone": "America/New_York",
      "population": 2736074,
      "isCapital": false,
      "distanceKm": 8.44
    …
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}
Nearest Danish city to Hamburg
GET /api/cities/nearest?lat=53.5511&lng=9.9937&country=DK&count=1 
{
  "data": [
    {
      "name": "Odense",
      "asciiName": "Odense",
      "country": "Denmark",
      "countryCode": "DK",
      "admin1": "South Denmark",
      "latitude": 55.3959,
      "longitude": 10.3883,
      "timezone": "Europe/Copenhagen",
      "population": 180863,
      "isCapital": false,
      "distanceKm": 206.71
    }
  ],
  "meta": {
    "endpoint": "cities",
    "route": "/nearest",
    "count": 1,
    "params": {
      "lat": 53.5511,
      "lng": 9.9937,
      "country": "DK"
    },
    "generatedAt": "2026-07-30T15:14:08.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

A pinned snapshot of the GeoNames cities500 dump covering 6,301 populated places across 245 countries and territories, including 240 national capitals. Records in the bundled dump were last modified upstream on 2026-07-28; the exact file is pinned by SHA-256 and regenerated by a committed script, never hand-edited.

What is in the set — an explicit, reproducible rule rather than an editor's taste:

  1. every populated place with a GeoNames population of 100,000 or more;
  2. plus the five most populous places of every country, so small countries are represented instead of dropped for being small;
  3. plus every place GeoNames codes PPLC (capital of a political entity), so a capital is never missing because it is tiny — Valletta (~6,800) and Ngerulmud are both here.

What is deliberately out: sections of populated places (GeoNames PPLX, i.e. neighbourhoods), historical/abandoned/destroyed places, and country codes outside officially assigned ISO 3166-1 alpha-2 — which drops GeoNames' user-assigned XK.

Honest caveats, all inherited from the upstream data:

  • Population is a GeoNames figure: an administrative/city-proper count of mixed vintage, not a metropolitan total. Paris reads ~2.1 million (the commune), not the ~11 million metro area. Use it for ordering and rough sizing, never as a census input. A handful of places have no published figure and return population: null.
  • isCapital mirrors PPLC exactly. GeoNames designates at most one capital per country, so in multi-capital states only its choice is flagged (Pretoria, not Cape Town), and a few entries — Israel and Western Sahara among them — have no capital row at all.
  • GeoNames records many urban subdivisions as populated places in their own right, so they sit next to their parent city: New York City and Brooklyn, Paris and the ten arrondissements that clear the population floor, Montreal's boroughs, Shanghai's districts. Sections explicitly coded PPLX are dropped, but these are not coded that way upstream — so /nearest around Paris legitimately returns Paris 15 Vaugirard before it reaches Montreuil. Raise minPopulation when you want one row per agglomeration.
  • Where GeoNames holds two records with the same name in the same first-order division, only the more populous one is kept.

All filters genuinely filter:

  • country takes an ISO 3166-1 alpha-2 code (case-insensitive) — DK returns every Danish place in the set, US returns hundreds. A well-formed code with no cities returns an empty list, never another country's. Malformed values are a 400.
  • search matches the name and the GeoNames ASCII alias, ignoring case, diacritics and apostrophes — sao paulo finds São Paulo, wroclaw finds Wrocław and xian finds Xi’an.
  • minPopulation keeps only places at or above the given figure; places with an unknown population are excluded, because "unknown" cannot be proven to clear the bar.
  • capital=true narrows to national capitals, capital=false excludes them.
  • sort=population (default) lists the largest first with unknown populations last; sort=name is alphabetical.
  • count caps a page at 100 records and offset skips ahead, so large result sets are pageable.
  • /nearest?lat=48.8566&lng=2.3522&maxDistanceKm=100 ranks the set by spherical great-circle distance — around Paris that is a genuine neighbourhood of results, not a single hit. It never geocodes and never invents a place that is not in the snapshot.

Use it for

  • Populate a city picker or autocomplete with real names, regions, countries and coordinates
  • Seed demo maps and dashboards with correctly geocoded markers at country or continent density
  • Test timezone-aware scheduling against real IANA zone names per city
  • Resolve the nearest real city to a coordinate for map, locale and timezone prototypes
  • Build a capitals-only reference list straight from the GeoNames PPLC classification

Frequently asked questions

Practical answers about this endpoint 6
Which cities are included?

Every place in the GeoNames cities500 snapshot with a population of 100,000 or more, plus the five largest places of every country and every GeoNames-designated capital — 6,301 places across 245 countries and territories.

Are the population figures metro-area numbers?

No. They are GeoNames figures, which are administrative/city-proper counts of mixed vintage. Paris reads about 2.1 million (the commune), not the roughly 11 million metropolitan area, and a few places return null because GeoNames publishes no figure.

Why do Brooklyn and the Paris arrondissements appear as separate cities?

Because GeoNames classifies them as populated places, not as sections of one. Rows explicitly coded PPLX are excluded, but these are not, so they sit alongside their parent city. Raise minPopulation if you want one row per agglomeration.

How do I get more than 100 cities?

Page through them: count caps a response at 100 records and offset skips ahead, so ?country=US&count=100&offset=100 returns the second hundred US places.

Does the nearest route search every city in the world?

No. It ranks only the 6,301 places in this bundled snapshot by great-circle distance; a place GeoNames does not include in the selection cannot be returned.

Is South Africa's capital Cape Town or Pretoria here?

Pretoria. isCapital mirrors the GeoNames PPLC feature code exactly, and GeoNames marks at most one capital per country, so multi-capital states show only its choice.

Standards & references

Primary sources behind the contract

Related APIs

Useful next tools in the catalog
Timezone Database API REAL DATA

Live IANA offsets, DST transitions, local-time ambiguity resolution and exact instant conversion — no guessed wall-clock mappings.
Random GPS Coordinates API MOCK DATA

Random geographic coordinates: uniform across the globe (no pole clustering), inside a bounding box, or within a radius of a point — with haversine distances.
ISO 4217 Currency Codes API REAL DATA

Every active ISO 4217 currency — code, name, symbol, minor-unit decimals and the countries using it. Search the list or look up one code, with honest 404s.
Mock Weather Data API MOCK DATA

Generated demo weather — NOT a forecast. Physically coherent records per climate profile: snow only below 4°C, storms bring wind, exact °F conversion.
GeoJSON Validator & Inspector API REAL DATA

Validate GeoJSON against RFC 7946: the exact clause behind an unclosed ring, a swapped lat/lng, clockwise winding or a wrong bbox — plus inspect and rewind.
ISO 3166-2 Subdivisions API — States, Provinces & Regions REAL DATA

ISO 3166-2 states, provinces and regions: 5,046 subdivision codes for 200 countries, with English names, parent codes and an auditable per-country index.