{ "openapi": "3.1.0", "info": { "title": "Continents, Countries And Cities API", "version": "1.0.0", "description": "252 countries, 7 continents and 235,640 cities from GeoNames with coordinates, population, timezone and names.\n\nContinents, countries and cities — rebuilt on GeoNames, the world''s reference geographical database: 235,640 cities and towns (every place with population 500+), 252 countries and all 7 continents, self-hosted and coherent. Every city carries real coordinates, population, elevation, IANA timezone, region (state/province) and alternate names (Múnich finds München); every country carries capital, ISO2/ISO3, area, population, currency code and name, languages, TLD, phone prefix and neighbouring countries; continents roll up their countries and population. Search cities by name prefix across native and ASCII spellings, filter by country, region or minimum population, and find every city near a coordinate with the distance-sorted nearby endpoint. Existing integrations keep working: the classic /continents, /countries and /cities paths and name/page/pageSize parameters are honoured. Data refreshes daily from GeoNames'' official modification feed (CC-BY 4.0, attribution included in every response). Built for signup forms, store locators, travel apps, shipping calculators and mapping tools. Self-hosted — no third-party calls at request time.", "contact": { "name": "Data and APIs", "url": "https://dataandapis.com/contact" }, "termsOfService": "https://dataandapis.com/terms-of-service", "license": { "name": "Data and APIs Terms of Service", "url": "https://dataandapis.com/terms-of-service" }, "x-logo": { "url": "https://dataandapis.com/images/geography.webp" } }, "externalDocs": { "description": "Documentation, live tester and pricing", "url": "https://dataandapis.com/apis/continents-countries-and-cities" }, "servers": [ { "url": "https://continents-countries-and-cities.dataandapis.com" } ], "tags": [ { "name": "Data", "description": "Continents, Countries And Cities API belongs to the Data category of the Data and APIs catalog." } ], "paths": { "/v1/cities": { "get": { "operationId": "cities", "summary": "cities", "description": "cities endpoint of the Continents, Countries And Cities API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/continents-countries-and-cities/cities" }, "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "example": "CO" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "20" }, { "name": "min_population", "in": "query", "required": false, "schema": { "type": "string" }, "example": "100000" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "example": "medellin" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "string" }, "example": "10" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Medell" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Antioquia" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "total": 7, "page": 1, "limit": 20, "count": 7, "attribution": "Data (c) GeoNames (geonames.org), CC-BY 4.0", "results": [ { "geonameid": 3674962, "name": "Medellín", "country_code": "CO", "country": "Colombia", "region": "Antioquia", "population": 1999979, "latitude": 6.245, "longitude": -75.57151, "timezone": "America/Bogota" }, { "geonameid": 1699896, "name": "Medellin", "country_code": "PH", "country": "Philippines", "region": "Central Visayas", "population": 11741, "latitude": 11.1286, "longitude": 123.9622, "timezone": "Asia/Manila" }, { "geonameid": 3802417, "name": "Medellín y Madero Segunda Sección", "country_code": "MX", "country": "Mexico", "region": "Tabasco", "population": 7825, "latitude": 18.11351, "longitude": -92.854, "timezone": "America/Mexico_City" }, { "geonameid": 3523387, "name": "Medellín de Bravo", "country_code": "MX", "country": "Mexico", "region": "Veracruz", "population": 2725, "latitude": 19.05869, "longitude": -96.15781, "timezone": "America/Mexico_City" }, { "geonameid": 2513968, "name": "Medellín", "country_code": "ES", "country": "Spain", "region": "Extremadura", "population": 2357, "latitude": 38.96265, "longitude": -5.95785, "timezone": "Europe/Madrid" }, { "geonameid": 8862302, "name": "Medellín", "country_code": "MX", "country": "Mexico", "region": "Veracruz", "population": 584, "latitude": 18.41639, "longitude": -95.36611, "timezone": "America/Mexico_City" }, { "geonameid": 3802441, "name": "Medellín y Pigua 1ra. Sección", "country_code": "MX", "country": "Mexico", "region": "Tabasco", "population": 529, "latitude": 18.02917, "longitude": -92.91278, "timezone": "America/Mexico_City" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/continents": { "get": { "operationId": "continents", "summary": "continents", "description": "continents endpoint of the Continents, Countries And Cities API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/continents-countries-and-cities/continents" }, "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "example": "North America" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "string" }, "example": "10" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "count": 7, "attribution": "Data (c) GeoNames (geonames.org), CC-BY 4.0", "results": [ { "code": "AF", "name": "Africa", "geonameid": 6255146, "countries": 58, "population": 1277404803 }, { "code": "AN", "name": "Antarctica", "geonameid": 6255152, "countries": 5, "population": 170 }, { "code": "AS", "name": "Asia", "geonameid": 6255147, "countries": 51, "population": 4542820771 }, { "code": "EU", "name": "Europe", "geonameid": 6255148, "countries": 54, "population": 753757455 }, { "code": "NA", "name": "North America", "geonameid": 6255149, "countries": 42, "population": 583536773 }, { "code": "OC", "name": "Oceania", "geonameid": 6255151, "countries": 28, "population": 43093797 }, { "code": "SA", "name": "South America", "geonameid": 6255150, "countries": 14, "population": 423597139 } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/countries": { "get": { "operationId": "countries", "summary": "countries", "description": "countries endpoint of the Continents, Countries And Cities API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/continents-countries-and-cities/countries" }, "parameters": [ { "name": "continent", "in": "query", "required": false, "schema": { "type": "string" }, "example": "SA" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "example": "EUR" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" }, "example": "es" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "50" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "example": "North America" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "string" }, "example": "10" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "example": "switzerland" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "total": 14, "page": 1, "limit": 3, "count": 3, "attribution": "Data (c) GeoNames (geonames.org), CC-BY 4.0", "results": [ { "iso2": "BR", "iso3": "BRA", "name": "Brazil", "capital": "Brasilia", "continent": "SA", "area_km2": 8511965, "population": 209469333, "currency_code": "BRL", "currency_name": "Real", "languages": "pt-BR,es,en,fr", "tld": ".br", "phone_prefix": "55", "neighbours": "SR,PE,BO,UY,GY,PY,GF,VE,CO,AR", "geonameid": 3469034 }, { "iso2": "CO", "iso3": "COL", "name": "Colombia", "capital": "Bogota", "continent": "SA", "area_km2": 1138910, "population": 49648685, "currency_code": "COP", "currency_name": "Peso", "languages": "es-CO", "tld": ".co", "phone_prefix": "57", "neighbours": "EC,PE,PA,BR,VE", "geonameid": 3686110 }, { "iso2": "AR", "iso3": "ARG", "name": "Argentina", "capital": "Buenos Aires", "continent": "SA", "area_km2": 2766890, "population": 44494502, "currency_code": "ARS", "currency_name": "Peso", "languages": "es-AR,en,it,de,fr,gn", "tld": ".ar", "phone_prefix": "54", "neighbours": "CL,BO,UY,PY,BR", "geonameid": 3865483 } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/sources": { "get": { "operationId": "dataSources", "summary": "data sources", "description": "data sources endpoint of the Continents, Countries And Cities API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/continents-countries-and-cities/data-sources" }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "count": 2, "sources": [ { "slug": "geonames-cities500", "name": "GeoNames cities500 (population >= 500)", "publisher": "GeoNames (geonames.org)", "licence": "CC-BY 4.0 - attribution required", "source_url": "https://www.geonames.org/", "file_url": "https://download.geonames.org/export/dump/cities500.zip", "cadence": "daily modifications", "record_count": 235640, "retrieved_at": "2026-09-02" }, { "slug": "geonames-countryinfo", "name": "GeoNames country information", "publisher": "GeoNames (geonames.org)", "licence": "CC-BY 4.0 - attribution required", "source_url": "https://www.geonames.org/", "file_url": "https://download.geonames.org/export/dump/countryInfo.txt", "cadence": "daily", "record_count": 252, "retrieved_at": "2026-09-02" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/cities/{id}": { "get": { "operationId": "getCityById", "summary": "get city by id", "description": "get city by id endpoint of the Continents, Countries And Cities API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/continents-countries-and-cities/get-city-by-id" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "1796236" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "geonameid": 3674962, "name": "Medellín", "country_code": "CO", "country": "Colombia", "region": "Antioquia", "population": 1999979, "latitude": 6.245, "longitude": -75.57151, "timezone": "America/Bogota", "ascii_name": "Medellin", "admin1_code": "02", "elevation_m": 1405, "is_capital": false, "feature_code": "PPLA", "alternate_names": [ "MDE", "Medegin", "Medehl'in", "Medel'in", "Medelim", "Medelin", "Medeljina", "Medeljinas", "Medeljino", "Medellin", "Medellín", "mai de lin", "mdlyn", "mdyyn", "me de yin", "medein", "medejin", "medelini", "medellina", "medeyina" ], "modified": "2026-04-13", "source": "Data (c) GeoNames (geonames.org), CC-BY 4.0" } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/continents/{id}": { "get": { "operationId": "getContinentById", "summary": "get continent by id", "description": "get continent by id endpoint of the Continents, Countries And Cities API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/continents-countries-and-cities/get-continent-by-id" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "EU" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "code": "EU", "name": "Europe", "geonameid": 6255148, "countries": [ { "iso2": "RU", "name": "Russia", "capital": "Moscow", "population": 144478050, "currency_code": "RUB" }, { "iso2": "DE", "name": "Germany", "capital": "Berlin", "population": 82927922, "currency_code": "EUR" }, { "iso2": "FR", "name": "France", "capital": "Paris", "population": 66987244, "currency_code": "EUR" }, { "iso2": "GB", "name": "United Kingdom", "capital": "London", "population": 66488991, "currency_code": "GBP" }, { "iso2": "IT", "name": "Italy", "capital": "Rome", "population": 60431283, "currency_code": "EUR" } ], "source": "Data (c) GeoNames (geonames.org), CC-BY 4.0" } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/countries/{id}": { "get": { "operationId": "getCountryById", "summary": "get country by id", "description": "get country by id endpoint of the Continents, Countries And Cities API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/continents-countries-and-cities/get-country-by-id" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "CO" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "iso2": "CH", "iso3": "CHE", "name": "Switzerland", "capital": "Bern", "continent": "EU", "area_km2": 41290, "population": 8516543, "currency_code": "CHF", "currency_name": "Franc", "languages": "de-CH,fr-CH,it-CH,rm", "tld": ".ch", "phone_prefix": "41", "neighbours": "DE,IT,LI,FR,AT", "geonameid": 2658434, "top_cities": [ { "geonameid": 2657896, "name": "Zürich", "region": "Zurich", "population": 415367, "feature_code": "PPLA", "is_capital": false }, { "geonameid": 2660646, "name": "Geneva", "region": "Geneva", "population": 201741, "feature_code": "PPLA", "is_capital": false }, { "geonameid": 2661604, "name": "Basel", "region": "Basel-City", "population": 177595, "feature_code": "PPLA", "is_capital": false }, { "geonameid": 2659994, "name": "Lausanne", "region": "Vaud", "population": 139111, "feature_code": "PPLA", "is_capital": false } ], "source": "Data (c) GeoNames (geonames.org), CC-BY 4.0" } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/cities/nearby": { "get": { "operationId": "nearbyCities", "summary": "nearby cities", "description": "nearby cities endpoint of the Continents, Countries And Cities API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/continents-countries-and-cities/nearby-cities" }, "parameters": [ { "name": "lat", "in": "query", "required": false, "schema": { "type": "string" }, "example": "51.51" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "20" }, { "name": "lon", "in": "query", "required": false, "schema": { "type": "string" }, "example": "-0.13" }, { "name": "radius", "in": "query", "required": false, "schema": { "type": "string" }, "example": "25" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "lat": 51.51, "lon": -0.13, "radius_km": 15, "count": 3, "attribution": "Data (c) GeoNames (geonames.org), CC-BY 4.0", "results": [ { "geonameid": 2643743, "name": "London", "country_code": "GB", "country": "United Kingdom", "region": "England", "population": 8961989, "latitude": 51.50853, "longitude": -0.12574, "timezone": "Europe/London", "distance_km": 0.3 }, { "geonameid": 6545173, "name": "Soho", "country_code": "GB", "country": "United Kingdom", "region": "England", "population": 19634, "latitude": 51.5144, "longitude": -0.13535, "timezone": "Europe/London", "distance_km": 0.6 }, { "geonameid": 6615507, "name": "St James's", "country_code": "GB", "country": "United Kingdom", "region": "England", "population": 10361, "latitude": 51.5073, "longitude": -0.13982, "timezone": "Europe/London", "distance_km": 0.7 } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Create a free key at https://dataandapis.com/sign-up. 500 tokens a month on the Free plan; this API costs 2 tokens per call." } } }, "security": [ { "ApiKey": [] } ] }