Tova Cities API
A fast, reliable API for querying city and country data worldwide. <200ms average response time with 56,000+ cities. Search cities by name, find nearby locations, or look up detailed information using universal codes.
Zero breaking changes. Existing API versions are permanent.
Popular Requests
Jump to the most common use cases:
Base URL
All API requests should be made to one of the following:
https://cities-v1.tovaapis.com
📋 Copy
pinned version, your integration never breaks
https://cities-latest.tovaapis.com
📋 Copy
always points to the newest version
Authentication
Include your API key in the request header:
X-API-Key: your_api_key
Endpoints
Search Cities versions: v1 latest
Search for cities by name within a specific country. Results are ordered by population (largest first).
GET
/search?q={query}&iso3={country}&n={limit}&contains={0|1}
Query Parameters
Parameter Type Required Description qstring Yes Search term (minimum 3 characters) iso3string Yes ISO-3 country code (e.g., USA, GBR) ninteger No Max results to return (1-100, default: 10) containsinteger No Set to 1 to match anywhere in name. Default (0) matches from beginning only.
Code Examples
https://cities-v1.tovaapis.com
https://cities-latest.tovaapis.com
cURL
Node.js
JavaScript
curl "https://cities-v1.tovaapis.com/search?q=Boulder&iso3=usa&n=3" \
-H "X-API-Key: your_api_key"
const params = new URLSearchParams ({
q: 'Boulder' ,
iso3: 'usa' ,
n: '3'
});
const response = await fetch (`https://cities-v1.tovaapis.com/search?${params}` , {
headers: { 'X-API-Key' : 'your_api_key' }
});
const result = await response.json ();
console.log (result.data);
const params = new URLSearchParams ({
q: 'Boulder' ,
iso3: 'usa' ,
n: '3'
});
fetch (`https://cities-v1.tovaapis.com/search?${params}` , {
headers: { 'X-API-Key' : 'your_api_key' }
})
.then (res => res.json ())
.then (result => {
console.log (result.data);
});
Example Response
{
"data" : [
{
"ucc" : "boul" ,
"name" : "Boulder" ,
"country" : "USA" ,
"countryName" : "United States" ,
"region" : "colorado" ,
"regionName" : "Colorado" ,
"population" : 108250 ,
"latitude" : 40.015 ,
"longitude" : -105.2705 ,
"aliases" : []
},
{
"ucc" : "boulde" ,
"name" : "Boulder City" ,
"country" : "USA" ,
"countryName" : "United States" ,
"region" : "nevada" ,
"regionName" : "Nevada" ,
"population" : 15551 ,
"latitude" : 35.9786 ,
"longitude" : -114.8325 ,
"aliases" : []
},
{
"ucc" : "bould" ,
"name" : "Boulder Hill" ,
"country" : "USA" ,
"countryName" : "United States" ,
"region" : "illinois" ,
"regionName" : "Illinois" ,
"population" : 8108 ,
"latitude" : 41.7125 ,
"longitude" : -88.3362 ,
"aliases" : []
}
],
"meta" : {
"query" : "Boulder" ,
"country" : "usa" ,
"total" : 3 ,
"limit" : 3
}
}
Find Nearest Cities versions: v1 latest
Find cities closest to a given coordinate. Results are ordered by distance (nearest first).
GET
/nearest?lat={lat}&lon={lon}&n={limit}&imp={0|1}
Query Parameters
Parameter Type Required Description latnumber Yes Latitude in decimal degrees (-90 to 90) lonnumber Yes Longitude in decimal degrees (-180 to 180) ninteger No Max results to return (1-100, default: 10) impinteger No Imperial. Set to 1 for miles, 0 (default) for kilometers
Code Examples
https://cities-v1.tovaapis.com
https://cities-latest.tovaapis.com
cURL
Node.js
JavaScript
curl "https://cities-v1.tovaapis.com/nearest?lat=40.7128&lon=-74.006&n=3" \
-H "X-API-Key: your_api_key"
const params = new URLSearchParams ({
lat: '40.7128' ,
lon: '-74.006' ,
n: '3'
});
const response = await fetch (`https://cities-v1.tovaapis.com/nearest?${params}` , {
headers: { 'X-API-Key' : 'your_api_key' }
});
const result = await response.json ();
result.data.forEach (city => {
console.log (`${city.name}: ${city.distance} ${city.distanceUnit}` );
});
const params = new URLSearchParams ({
lat: '40.7128' ,
lon: '-74.006' ,
n: '3'
});
fetch (`https://cities-v1.tovaapis.com/nearest?${params}` , {
headers: { 'X-API-Key' : 'your_api_key' }
})
.then (res => res.json ())
.then (result => {
result.data.forEach (city => {
console.log (`${city.name}: ${city.distance} ${city.distanceUnit}` );
});
});
Example Response
{
"data" : [
{
"distance" : 0.0 ,
"distanceUnit" : "km" ,
"ucc" : "nyc" ,
"name" : "New York" ,
"country" : "USA" ,
"countryName" : "United States" ,
"region" : "newyork" ,
"regionName" : "New York" ,
"population" : 8336817 ,
"latitude" : 40.7128 ,
"longitude" : -74.006 ,
"aliases" : ["NYC" , "New York City" , "Nueva York" , "The Big Apple" , "Gotham" ]
},
{
"distance" : 0.4 ,
"distanceUnit" : "km" ,
"ucc" : "trib" ,
"name" : "Tribeca" ,
"country" : "USA" ,
"countryName" : "United States" ,
"region" : "newyork" ,
"regionName" : "New York" ,
"population" : 7811 ,
"latitude" : 40.7154 ,
"longitude" : -74.0093 ,
"aliases" : []
},
{
"distance" : 0.6 ,
"distanceUnit" : "km" ,
"ucc" : "fina" ,
"name" : "Financial District" ,
"country" : "USA" ,
"countryName" : "United States" ,
"region" : "newyork" ,
"regionName" : "New York" ,
"population" : 60976 ,
"latitude" : 40.7079 ,
"longitude" : -74.0086 ,
"aliases" : []
}
],
"meta" : {
"latitude" : 40.7128 ,
"longitude" : -74.006 ,
"limit" : 3
}
}
Get Country versions: v1 latest
Retrieve detailed information about a country using its ISO 3166-1 alpha-3 code.
GET
/countries/{iso3}
Path Parameters
Parameter Type Description iso3string ISO-3 country code (e.g., USA, GBR, JPN)
Code Examples
https://cities-v1.tovaapis.com
https://cities-latest.tovaapis.com
cURL
Node.js
JavaScript
curl "https://cities-v1.tovaapis.com/countries/USA" \
-H "X-API-Key: your_api_key"
const response = await fetch ('https://cities-v1.tovaapis.com/countries/USA' , {
headers: { 'X-API-Key' : 'your_api_key' }
});
const country = await response.json ();
console.log (`${country.name} has ${country.cityCount} cities` );
fetch ('https://cities-v1.tovaapis.com/countries/USA' , {
headers: { 'X-API-Key' : 'your_api_key' }
})
.then (res => res.json ())
.then (country => {
console.log (`${country.name} has ${country.cityCount} cities` );
});
Example Response
{
"iso3" : "USA" ,
"iso2" : "US" ,
"name" : "United States" ,
"population" : 331900000 ,
"capital" : "wash" ,
"capitalName" : "Washington" ,
"regionCount" : 51 ,
"cityCount" : 7502 ,
"currency" : "USD"
}
Get City by UCC versions: v1 latest
Retrieve detailed information about a city using its Universal City Code (UCC).
GET
/cities/{ucc}
Path Parameters
Parameter Type Description uccstring Universal City Code (e.g., nyc)
Code Examples
https://cities-v1.tovaapis.com
https://cities-latest.tovaapis.com
cURL
Node.js
JavaScript
curl "https://cities-v1.tovaapis.com/cities/nyc" \
-H "X-API-Key: your_api_key"
const response = await fetch ('https://cities-v1.tovaapis.com/cities/nyc' , {
headers: { 'X-API-Key' : 'your_api_key' }
});
const city = await response.json ();
console.log (city.name);
fetch ('https://cities-v1.tovaapis.com/cities/nyc' , {
headers: { 'X-API-Key' : 'your_api_key' }
})
.then (res => res.json ())
.then (city => {
console.log (city.name);
});
Example Response
{
"ucc" : "nyc" ,
"name" : "New York" ,
"country" : "USA" ,
"countryName" : "United States" ,
"region" : "newyork" ,
"regionName" : "New York" ,
"population" : 8336817 ,
"latitude" : 40.7128 ,
"longitude" : -74.006 ,
"aliases" : ["NYC" , "New York City" , "Nueva York" , "The Big Apple" , "Gotham" ]
}
Response Fields
City Object
Field Type Description uccstring Universal City Code - unique identifier for the city namestring City name countrystring ISO-3 country code countryNamestring Full country name regionstring Universal Region Code (state/province) regionNamestring Region name populationinteger City population latitudenumber Latitude in decimal degrees longitudenumber Longitude in decimal degrees aliasesarray Alternative names for the city
Country Object
Field Type Description iso3string ISO-3 country code iso2string ISO 3166-1 alpha-2 country code namestring Country name populationinteger Country population capitalstring UCC of the capital city capitalNamestring Name of the capital city regionCountinteger Number of regions/states cityCountinteger Number of cities in database currencystring Currency code
Error Responses
The API returns standard HTTP status codes along with a JSON error body:
{
"error" : {
"code" : "CITY_NOT_FOUND" ,
"message" : "UCC doesn't exist" ,
"statusCode" : 404 ,
"requestID" : "9c00d1e5-5cbb-4622-a313-12cf84262d6a" ,
"field" : null
}
}
Status Code Error Code Description 400 MISSING_PARAMETERA required parameter is missing 400 INVALID_PARAMETERA parameter value is invalid 400 INVALID_COORDINATESLatitude or longitude is out of range 404 CITY_NOT_FOUNDThe requested city does not exist 404 COUNTRY_NOT_FOUNDThe requested country does not exist 429 RATE_LIMIT_EXCEEDEDToo many requests
Getting Started
1. Get Your Test Key (Free) 1,000 free requests . This is enough to explore endpoints and build your integration.
Rate Limits
Test Key: 1,000 lifetime requests, 10 requests per secondLive Key: Per your plan quota
Search Cities
Find cities by name in any country
Find Nearest Cities
Get cities closest to coordinates
Get Country Info
Country details by ISO code