{"openapi":"3.1.0","info":{"title":"World Cities API","version":"1.0.0","description":"Search a database of 33,000+ cities worldwide (population 15,000+) from GeoNames. Find cities by name, country and minimum population, look up a city by id, or find all cities near a coordinate (radius search). Each city includes coordinates, region, population, timezone and elevation — ideal for autocompletes, location pickers, store locators and geo dashboards.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/cities-api","description":"oanor gateway"}],"tags":[{"name":"Cities"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/city":{"get":{"operationId":"get_v1_city","tags":["Cities"],"summary":"A single city by GeoNames id","description":"","parameters":[{"name":"id","in":"query","required":true,"description":"GeoNames id","schema":{"type":"string"},"example":"2950159"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"id":2950159,"name":"Berlin","ascii":"Berlin","admin1":"16","country":"DE","latitude":52.52437,"timezone":"Europe/Berlin","longitude":13.41053,"population":3426354,"elevation_m":74,"country_name":"Germany"},"meta":{"timestamp":"2026-05-30T23:56:39.891Z","request_id":"71c5bd5a-cebc-42f8-8e94-599102c13cf2"},"status":"ok","message":"City retrieved","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/nearby":{"get":{"operationId":"get_v1_nearby","tags":["Cities"],"summary":"Cities near a coordinate (radius search)","description":"","parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude (-90..90)","schema":{"type":"string"},"example":"48.8566"},{"name":"lon","in":"query","required":true,"description":"Longitude (-180..180)","schema":{"type":"string"},"example":"2.3522"},{"name":"radius_km","in":"query","required":false,"description":"Search radius in km (1-2000, default 100)","schema":{"type":"string"},"example":"50"},{"name":"min_population","in":"query","required":false,"description":"Minimum population filter","schema":{"type":"string"},"example":"0"},{"name":"limit","in":"query","required":false,"description":"Max results (1-100, default 20)","schema":{"type":"string"},"example":"20"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":20,"center":{"lat":48.8566,"lon":2.3522},"results":[{"id":3013131,"name":"Paris 04 Hôtel-de-Ville","ascii":"Paris 04 Hotel-de-Ville","admin1":"11","country":"FR","latitude":48.8601,"timezone":"Europe/Paris","longitude":2.3507,"population":27332,"distance_km":0.4,"country_name":"France"},{"id":2988507,"name":"Paris","ascii":"Paris","admin1":"11","country":"FR","latitude":48.85341,"timezone":"Europe/Paris","longitude":2.3488,"population":2138551,"distance_km":0.43,"country_name":"France"},{"id":6269531,"name":"Paris 01 Louvre","ascii":"Paris 01 Louvre","admin1":"11","country":"FR","latitude":48.8592,"timezone":"Europe/Paris","longitude":2.3417,"population":15114,"distance_km":0.82,"country_name":"France"},{"id":2973189,"name":"Paris 03 Temple","ascii":"Paris 03 Temple","admin1":"11","country":"FR","latitude":48.8637,"timezone":"Europe/Paris","longitude":2.3615,"population":32179,"distance_km":1.04,"country_name":"France"},{"id":3030864,"name":"Paris 02 Bourse","ascii":"Paris 02 Bourse","admin1":"11","country":"FR","latitude":48.8655,"timezone":"Europe/Paris","longitude":2.3426,"population":19847,"distance_km":1.21,"country_name":"France"},{"id":2988623,"name":"Paris 05 Panthéon","ascii":"Paris 05 Pantheon","admin1":"11","country":"FR","latitude":48.8448,"timezone":"Europe/Paris","longitude":2.3471,"population":55252,"distance_km":1.36,"country_name":"France"},{"id":3020216,"name":"Paris 10 Entrepôt","ascii":"Paris 10 Entrepot","admin1":"11","country":"FR","latitude":48.8709,"timezone":"Europe/Paris","longitude":2.3561,"population":83873,"distance_km":1.62,"country_name":"France"},{"id":12808656,"name":"Porte Saint-Martin","ascii":"Porte Saint-Martin","admin1":"11","country":"FR","latitude":48.87153,"timezone":"Europe/Paris","longitude":2.36015,"population":21154,"distance_km":1.76,"country_name":"France"},{"id":12808659,"name":"Folie Méricourt","ascii":"Folie Mericourt","admin1":"11","country":"FR","latitude":48.86625,"timezone":"Europe/Paris","longitude":2.37142,"population":31299,"distance_km":1.77,"country_name":"France"},{"id":12808661,"name":"Saint-Ambroise","ascii":"Saint-Ambroise","admin1":"11","country":"FR","latitude":48.86174,"timezone":"Europe/Paris","longitude":2.37538,"population":30802,"distance_km":1.79,"country_name":"France"},{"id":2997000,"name":"Paris 06 Luxembourg","ascii":"Paris 06 Luxembourg","admin1":"11","country":"FR","latitude":48.8493,"timezone":"Europe/Paris","longitude":2.33,"population":40389,"distance_km":1.82,"country_name":"France"},{"id":12808655,"name":"Porte Saint-Denis","ascii":"Porte Saint-Denis","admin1":"11","country":"FR","latitude":48.87363,"timezone":"Europe/Paris","longitude":2.35197,"population":15063,"distance_km":1.89,"country_name":"France"},{"id":2989487,"name":"Paris 09 Opéra","ascii":"Paris 09 Opera","admin1":"11","country":"FR","latitude":48.8718,"timezone":"Europe/Paris","longitude":2.3399,"population":57271,"distance_km":1.91,"country_name":"France"},{"id":12306362,"name":"Quinze-Vingts","ascii":"Quinze-Vingts","admin1":"11","country":"FR","latitude":48.84656,"timezone":"Europe/Paris","longitude":2.37439,"population":26265,"distance_km":1.97,"country_name":"France"},{"id":2986082,"name":"Paris 11 Popincourt","ascii":"Paris 11 Popincourt","admin1":"11","country":"FR","latitude":48.8574,"timezone":"Europe/Paris","longitude":2.3795,"population":138170,"distance_km":2,"country_name":"France"},{"id":12808658,"name":"Paris 11e Arrondissement","ascii":"Paris 11e Arrondissement","admin1":"11","country":"FR","latitude":48.85834,"timezone":"Europe/Paris","longitude":2.37952,"population":144292,"distance_km":2.01,"country_name":"France"},{"id":12808660,"name":"Roquette","ascii":"Roquette","admin1":"11","country":"FR","latitude":48.858,"timezone":"Europe/Paris","longitude":2.38147,"population":45842,"distance_km":2.15,"country_name":"France"},{"id":12808677,"name":"Salpêtrière","ascii":"Salpetriere","admin1":"11","country":"FR","latitude":48.83732,"timezone":"Europe/Paris","longitude":2.35823,"population":17708,"distance_km":2.19,"country_name":"France"},{"id":2988760,"name":"Paris 07 Palais-Bourbon","ascii":"Paris 07 Palais-Bourbon","admin1":"11","country":"FR","latitude":48.8565,"timezone":"Europe/Paris","longitude":2.321,"population":48015,"distance_km":2.28,"country_name":"France"},{"id":12808653,"name":"Paris 10e Arrondissement","ascii":"Paris 10e Arrondissement","admin1":"11","country":"FR","latitude":48.87668,"timezone":"Europe/Paris","longitude":2.35904,"population":83459,"distance_km":2.29,"country_name":"France"}],"radius_km":50},"meta":{"timestamp":"2026-05-30T23:56:39.977Z","request_id":"7e830118-85b4-4964-9581-1ca6dc2a9a26"},"status":"ok","message":"Nearby cities retrieved","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/search":{"get":{"operationId":"get_v1_search","tags":["Cities"],"summary":"Search cities by name, country and population","description":"","parameters":[{"name":"q","in":"query","required":false,"description":"City name (substring match)","schema":{"type":"string"},"example":"berlin"},{"name":"country","in":"query","required":false,"description":"Filter by ISO-2 country code","schema":{"type":"string"},"example":"DE"},{"name":"min_population","in":"query","required":false,"description":"Minimum population","schema":{"type":"string"},"example":"100000"},{"name":"limit","in":"query","required":false,"description":"Results per page (1-100, default 20)","schema":{"type":"string"},"example":"20"},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"string"},"example":"0"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":1,"limit":20,"total":1,"offset":0,"filters":{"q":"berlin","country":"DE","min_population":100000},"results":[{"id":2950159,"name":"Berlin","ascii":"Berlin","admin1":"16","country":"DE","latitude":52.52437,"timezone":"Europe/Berlin","longitude":13.41053,"population":3426354,"elevation_m":74,"country_name":"Germany"}]},"meta":{"timestamp":"2026-05-30T23:56:40.051Z","request_id":"338e1c46-04ab-4127-9791-6d9630439f55"},"status":"ok","message":"Search completed","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Dataset totals & largest cities","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"total":33744,"fields":["id","name","ascii","country","country_name","admin1","latitude","longitude","population","timezone","elevation_m"],"source":"GeoNames (cities with population ≥ 15,000)","largest":[{"name":"Shanghai","country":"CN","population":24874500},{"name":"Beijing","country":"CN","population":18960744},{"name":"Shenzhen","country":"CN","population":17494398},{"name":"Guangzhou","country":"CN","population":16096724},{"name":"Kinshasa","country":"CD","population":16000000}],"countries":244},"meta":{"timestamp":"2026-05-30T23:56:40.126Z","request_id":"8104c41e-acc4-478f-bb55-2f036f521847"},"status":"ok","message":"Meta retrieved","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":5000,"rps_limit":3,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":700,"monthly_call_quota":150000,"rps_limit":12,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1900,"monthly_call_quota":1250000,"rps_limit":40,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":5200,"monthly_call_quota":8000000,"rps_limit":120,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/cities-api"}