Authentication
Every request requires an API key sent via the X-API-KEY header. Keys are generated in the dashboard and can be revoked instantly. Keep them out of client-side code or public repositories.
Request header
X-API-KEY: your_api_key_hereFor server-to-server integrations store the key in an environment variable:
Environment variable
# .env
CITYDATA_API_KEY=your_api_key_hereMaking requests
All endpoints are served over HTTPS, return JSON, and support gzip compression. Rate limits vary by plan; at 80% usage we notify you via email and optional webhook.
Include your API key in every request and set a descriptive User-Agent so we can help troubleshoot quickly.
cURL
curl -G "https://api.citydata.dev/v1/cities/search" -H "X-API-KEY: $CITYDATA_API_KEY" --data-urlencode "q=Lisbon"JavaScript fetch
const response = await fetch('https://api.citydata.dev/v1/cities/search?q=Lisbon', {
headers: {
'X-API-KEY': process.env.CITYDATA_API_KEY!,
},
});
const results = await response.json();
console.log(results[0]);City search endpoint
Search cities with typo tolerance, synonyms, and population-aware ranking. Combine optional filters to narrow by country or minimum population.
ParameterTypeDescription
qstring (required)City name fragment or full name. Fuzzy matching enabled.countrystringISO 3166-1 alpha-2 code to limit results to a country.limitnumberMaximum number of records (default 10, max 100).min_populationnumberOnly return cities with a population above the threshold.Response schema
Successful requests return an array of city objects. Use the layout below to familiarise yourself with each field.
Example response
[
{
"name": "Lisbon/Portugal",
"info": {
"geonameid": 2267057,
"name": "Lisbon",
"ascii_name": "Lisbon",
"country_name": "Portugal",
"country_code": "PT",
"latitude": "38.725090",
"longitude": "-9.149800",
"population": 517802,
"timezone": "Europe/Lisbon"
}
},
{
"name": "Libon/Philippines",
"info": {
"geonameid": 1706609,
"name": "Libon",
"ascii_name": "Libon",
"country_name": "Philippines",
"country_code": "PH",
"latitude": "13.299700",
"longitude": "123.438600",
"population": 68846,
"timezone": "Asia/Manila"
}
},
{
"name": "João Lisboa/Brazil",
"info": {
"geonameid": 3397292,
"name": "João Lisboa",
"ascii_name": "Joao Lisboa",
"country_name": "Brazil",
"country_code": "BR",
"latitude": "-5.447780",
"longitude": "-47.400830",
"population": 24709,
"timezone": "America/Fortaleza"
}
},
{
"name": "Lisbon/United States",
"info": {
"geonameid": 4969622,
"name": "Lisbon",
"ascii_name": "Lisbon",
"country_name": "United States",
"country_code": "US",
"latitude": "44.031460",
"longitude": "-70.104500",
"population": 9392,
"timezone": "America/New_York"
}
},
{
"name": "Histon/United Kingdom",
"info": {
"geonameid": 2646828,
"name": "Histon",
"ascii_name": "Histon",
"country_name": "United Kingdom",
"country_code": "GB",
"latitude": "52.251660",
"longitude": "0.106430",
"population": 7592,
"timezone": "Europe/London"
}
},
{
"name": "Leiston/United Kingdom",
"info": {
"geonameid": 2644642,
"name": "Leiston",
"ascii_name": "Leiston",
"country_name": "United Kingdom",
"country_code": "GB",
"latitude": "52.206110",
"longitude": "1.577570",
"population": 6495,
"timezone": "Europe/London"
}
},
{
"name": "Clisson/France",
"info": {
"geonameid": 3024578,
"name": "Clisson",
"ascii_name": "Clisson",
"country_name": "France",
"country_code": "FR",
"latitude": "47.087100",
"longitude": "-1.282970",
"population": 6480,
"timezone": "Europe/Paris"
}
},
{
"name": "Santo Antônio de Lisboa/Brazil",
"info": {
"geonameid": 3389069,
"name": "Santo Antônio de Lisboa",
"ascii_name": "Santo Antonio de Lisboa",
"country_name": "Brazil",
"country_code": "BR",
"latitude": "-6.981390",
"longitude": "-41.234170",
"population": 5839,
"timezone": "America/Fortaleza"
}
},
{
"name": "Libona/Philippines",
"info": {
"geonameid": 1706607,
"name": "Libona",
"ascii_name": "Libona",
"country_name": "Philippines",
"country_code": "PH",
"latitude": "8.338890",
"longitude": "124.735280",
"population": 5713,
"timezone": "Asia/Manila"
}
},
{
"name": "Lisbon/United States",
"info": {
"geonameid": 4837798,
"name": "Lisbon",
"ascii_name": "Lisbon",
"country_name": "United States",
"country_code": "US",
"latitude": "41.603990",
"longitude": "-72.011740",
"population": 4234,
"timezone": "America/New_York"
}
}
]FieldTypeDescription
namestringFormatted label combining city and country.info.geonameidnumberStable identifier for the place.info.namestringCanonical city name as returned by official sources.info.ascii_namestringASCII variant for slugging or URLs.info.country_namestringHuman-friendly country name.info.country_codestringISO 3166-1 alpha-2 country code.info.latitudestringDecimal degrees latitude.info.longitudestringDecimal degrees longitude.info.populationnumberLatest population estimate when available.info.timezonestringIANA timezone identifier.Rate limits
Successful requests return standard rate limit headers so you can back off gracefully.
Example success payload
[
{
"name": "Lisbon/Portugal",
"info": {
"geonameid": 2267057,
"name": "Lisbon",
"ascii_name": "Lisbon",
"country_name": "Portugal",
"country_code": "PT",
"latitude": "38.725090",
"longitude": "-9.149800",
"population": 517802,
"timezone": "Europe/Lisbon"
}
},
{
"name": "Libon/Philippines",
"info": {
"geonameid": 1706609,
"name": "Libon",
"ascii_name": "Libon",
"country_name": "Philippines",
"country_code": "PH",
"latitude": "13.299700",
"longitude": "123.438600",
"population": 68846,
"timezone": "Asia/Manila"
}
},
{
"name": "João Lisboa/Brazil",
"info": {
"geonameid": 3397292,
"name": "João Lisboa",
"ascii_name": "Joao Lisboa",
"country_name": "Brazil",
"country_code": "BR",
"latitude": "-5.447780",
"longitude": "-47.400830",
"population": 24709,
"timezone": "America/Fortaleza"
}
},
{
"name": "Lisbon/United States",
"info": {
"geonameid": 4969622,
"name": "Lisbon",
"ascii_name": "Lisbon",
"country_name": "United States",
"country_code": "US",
"latitude": "44.031460",
"longitude": "-70.104500",
"population": 9392,
"timezone": "America/New_York"
}
},
{
"name": "Histon/United Kingdom",
"info": {
"geonameid": 2646828,
"name": "Histon",
"ascii_name": "Histon",
"country_name": "United Kingdom",
"country_code": "GB",
"latitude": "52.251660",
"longitude": "0.106430",
"population": 7592,
"timezone": "Europe/London"
}
},
{
"name": "Leiston/United Kingdom",
"info": {
"geonameid": 2644642,
"name": "Leiston",
"ascii_name": "Leiston",
"country_name": "United Kingdom",
"country_code": "GB",
"latitude": "52.206110",
"longitude": "1.577570",
"population": 6495,
"timezone": "Europe/London"
}
},
{
"name": "Clisson/France",
"info": {
"geonameid": 3024578,
"name": "Clisson",
"ascii_name": "Clisson",
"country_name": "France",
"country_code": "FR",
"latitude": "47.087100",
"longitude": "-1.282970",
"population": 6480,
"timezone": "Europe/Paris"
}
},
{
"name": "Santo Antônio de Lisboa/Brazil",
"info": {
"geonameid": 3389069,
"name": "Santo Antônio de Lisboa",
"ascii_name": "Santo Antonio de Lisboa",
"country_name": "Brazil",
"country_code": "BR",
"latitude": "-6.981390",
"longitude": "-41.234170",
"population": 5839,
"timezone": "America/Fortaleza"
}
},
{
"name": "Libona/Philippines",
"info": {
"geonameid": 1706607,
"name": "Libona",
"ascii_name": "Libona",
"country_name": "Philippines",
"country_code": "PH",
"latitude": "8.338890",
"longitude": "124.735280",
"population": 5713,
"timezone": "Asia/Manila"
}
},
{
"name": "Lisbon/United States",
"info": {
"geonameid": 4837798,
"name": "Lisbon",
"ascii_name": "Lisbon",
"country_name": "United States",
"country_code": "US",
"latitude": "41.603990",
"longitude": "-72.011740",
"population": 4234,
"timezone": "America/New_York"
}
}
]When limits are exceeded
{
"statusCode": 429,
"message": "You have reached the maximum daily request limit. Please upgrade for more daily requests."
}Rate limit headers
Retry-After: 35113
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1759104000507Retry-After is expressed in seconds. X-RateLimit-Reset is a Unix timestamp (milliseconds) indicating when counts reset.
Next steps
Ready for production? Monitor usage, rotate keys, and configure webhooks directly from your dashboard. Have questions or need a feature? We are one message away.