City lookup · Autocomplete · Nearby places
City API
Choose a city.
Keep the right place.
Find the right city for your form, map or listings. Get its location, timezone and stable id.
Enter a city name.
Try itcountry=US
One API. Several useful tasks.
A place your app
can work with.
Start with a city lookup. Use the same key for search, nearby places and population. See the request and complete JSON for each task.
A city your app can use.
Location, timezone, native name and a stable id in one response.
Request
curl "https://api.parseapi.com/city/miami?country=US&deep=true" \
-H "X-API-Key: YOUR_API_KEY"Example response
City autocomplete
The right place.
From the first letters.
Let someone choose their city. A name, state and country make the choice clear. A stable id keeps it clear in your app.
Add city autocompleteExample city choices · Japan
kita
Kita 北区
Tokyo · JP · ward
Kitakyushu Kokurakita
Fukuoka · JP · ward
Narrow the search by country or state. Save the selected id.
Place identity
The city.
And its wards.
Keep a whole municipality distinct from a neighborhood or ward. Add hierarchy to see available parent relationships.
Readable names come first. The native form stays beside them when it differs.
Explore place relationshipsMunicipality
Kitakyushu
北九州市
city_6pqpxzvw8hbc
Ward · subdivision
Kitakyushu Kokurakita
北九州市小倉北区
city_evrmz274v6qu
Nearby cities
Find nearby places.
Find the nearest recorded city, or the places inside your radius. Choose kilometers or miles. Get distance in both.
From a city.
Put the places around Miami into a search, a booking flow or a local directory.
GET /city/miami/nearby?country=US&radius=20&unit=km
From coordinates.
Turn a map pin or GPS reading into the nearest place name and its timezone.
GET /city?lat=25.7752&lon=-80.2086
Distances compare recorded city centers. They describe straight-line distance; they do not establish boundary membership or travel time.
Optional Deep
Population.
In context.
Read the count alongside its place identity. Population, area and elevation stay together in the same response.
Add Deep for available area, elevation and capital status in the same response.
Read the Deep fields- Miami · Florida
- 487,014
- Area
- 145.23 km²
City search filters
The places
your product needs.
Narrow search and nearby results to the places your app needs.
Explore filters and pages- A place, precisely
- Country, state, place type or municipality.
- The right scope
- Population range, exact timezone or a map box.
- An order you choose
- Name or population. Nearest first for nearby places.
- Pages that keep their context
- Use next_cursor as cursor. Keep the same options.
City → Time · Holiday · Weather
Put a city on your calendar.
A selected city gives you a timezone, country code and coordinates. Use them for local time, public holidays and weather near the city.
Choose the city
/city/miami?country=US
Fields from the response
{
"country": "US",
"latitude": 25.775163,
"longitude": -80.208615,
"timezone": "America/New_York"
}Miami returns timezone America/New_York and country US. If several places match your input, use search and save the selected city id.
Use
timezoneGet its local time
/time/America/New_York
Use the returned timezone for local clocks or to convert an event’s time for the city.
Use
countryLoad its country’s holidays
/holiday/US/2026
Use the city’s country code with the calendar year. Apply the supported region when regional holidays matter.
Use the calendar year you need
Use
latitude+longitudeGet weather near the city
/weather?lat=25.775163&lon=-80.208615
Use the city's reference coordinates for the nearest supported station's observation. The response includes its reading time and distance.
Use the local date for calendar decisions. A public holiday does not determine whether a particular business is open.
Use this in your app
// Run on your server with PARSEAPI_KEY in the environment.
const key = process.env.PARSEAPI_KEY;
if (!key) throw new Error('Set PARSEAPI_KEY on your server.');
const segment = value => encodeURIComponent(value);
const timezonePath = zone => zone.split('/').map(segment).join('/');
async function lookup(path, query = {}) {
const url = new URL(path, 'https://api.parseapi.com');
url.search = new URLSearchParams(query).toString();
const response = await fetch(url, {
headers: { 'X-API-Key': key, 'Parse-Version': '2.0.0' },
signal: AbortSignal.timeout(10000),
});
if (!response.ok) {
const error = await response.json().catch(() => null);
throw new Error(error?.message ?? 'ParseAPI returned HTTP ' + response.status);
}
return response.json();
}
const city = await lookup('/city/miami', { country: 'US' });
const calendarYear = '2026'; // The year selected in your calendar.
const [time, holidays, weather] = await Promise.all([
city.timezone ? lookup('/time/' + timezonePath(city.timezone)) : null,
city.country
? lookup('/holiday/' + segment(city.country) + '/' + segment(calendarYear))
: null,
Number.isFinite(city.latitude) && Number.isFinite(city.longitude)
? lookup('/weather', { lat: String(city.latitude), lon: String(city.longitude) })
: null,
]);
console.log({ city, time, holidays, weather });Add form.js to your fields
Let people pick the city they mean.
Add city suggestions to an existing input with form.js. A selected result can fill the state and save the stable city id alongside the name.
Try city autocompleteInclude the script once with your website's domain-restricted public key. Use these bindings in your existing form.
<script src="https://cdn.parseapi.com/v1/form.js"
data-key="parse_public_YOUR_KEY" defer></script>
<label for="form-city">City</label>
<input id="form-city" name="city" autocomplete="address-level2"
data-parse="city" data-parse-country="US">
<label for="form-region">State</label>
<input id="form-region" name="state"
data-parse-from="form-city" data-parse-fill="state_name">
<input type="hidden" name="city_id"
data-parse-from="form-city" data-parse-fill="id">Coverage and confidence
See what's covered.
City records cover 36 countries and territories. Available names, statistics and relationships vary by source. Missing facts stay null.
- Argentina
- Austria
- Australia
- Belgium
- Brazil
- Canada
- Switzerland
- Czechia
- Germany
- Denmark
- Estonia
- Spain
- Finland
- France
- United Kingdom
- French Guiana
- Guadeloupe
- Ireland
- Italy
- Japan
- Liechtenstein
- Luxembourg
- Martinique
- Mexico
- Netherlands
- Norway
- New Zealand
- Poland
- Puerto Rico
- Portugal
- Réunion
- Sweden
- Slovakia
- Taiwan
- United States
- Mayotte
From the first request to your app
One integration.
Places throughout your app.
Use City in a signup form, a listings filter or a map. Keep the selected id, then fetch the same place when you need it.
Explore the response fields
Response fields
- namestring or null
- City name
- name_localstring or null
- Local-language name, null when absent or identical to name
- typestring or null
- What the place is in its own country's words (city, town, commune, ward)
- districtstring or null
- District code the city sits in (US FIPS, FR INSEE, GB GSS)
- district_namestring or null
- District name
- statestring or null
- State or province code
- state_namestring or null
- State or province name
- countrystring or null
- ISO2 country code
- country_namestring or null
- Country name
- latitudenumber or null
- Latitude
- longitudenumber or null
- Longitude
- timezonestring or null
- Timezone identifier
- distancenumber
- Kilometers from query point (coords and nearby)
- distance_minumber
- Miles from query point (coords and nearby)
- grainstring or null
- Reviewed geographic layer, returned with hierarchy=true; null when unreviewed
- parentobject or null
- Reviewed immediate parent with its City id, name, name_local, country, state, type and grain; returned with hierarchy=true, null when unreviewed
- idstring or null
- Stable city id (city_...). Fetch again at /city/id/{id}
Deep fields
- deep.capital_ofstring or null
- country when it is a national capital, state when it is a state or region capital, null otherwise
- deep.elevationinteger or null
- Elevation in meters at the city center
- deep.elevation_ftinteger or null
- Elevation in feet
- deep.populationinteger or null
- Population
- deep.population_observed_onstring
- Exact observation date for a reviewed count at this place layer; omitted for legacy undated counts
- deep.population_basisstring
- Published counting basis, such as household registration or usual residence; omitted when unreviewed
- deep.areanumber or null
- Total area in km² (land + water, or the official total)
- deep.land_areanumber or null
- Land area in km² (null when the source publishes total only)
- deep.water_areanumber or null
- Water area in km² (null when the source publishes total only)
Before you build.
Can I add city autocomplete to my form?
Yes. Search a prefix with q, display the returned choices, then save the selected id. Country and state codes help distinguish places with the same name. Use a domain-restricted public key in the browser or keep your secret key on your server.
What if several cities have the same name?
A name lookup selects the largest matching record by its recorded population. Narrow it with country, state, type or grain. Use ambiguity=error to reject multiple matches, or use search to let the person choose. Save the selected id to fetch that same place again.
Does nearest mean the point is inside the city?
Nearest compares your coordinate with recorded city centers. It does not test municipal boundaries. Nearby distance is also straight-line, rather than road distance or travel time.
Can I filter and page the results?
Filter search and nearby results by population range, timezone and a map box. Choose name, population or distance ordering where applicable. Copy next_cursor into the next request and keep the same options. Unknown populations are excluded from population ranges.
Is a city population always comparable?
Counts describe the source’s published place boundary. A municipality, a ward and a statistical settlement can measure different things. Deep returns an exact observation date and population basis for reviewed records when available. Unknown counts stay null. Unverified observation dates and counting bases are omitted.
What does hierarchy return?
hierarchy=true adds a reviewed grain and immediate parent where available. Whole municipalities and their wards keep separate ids. Not every record has a reviewed relationship; unknown grain or parent stays null.
Which languages are available?
name uses a readable source name, with name_local when a different native form is available. lang changes available display names and location labels. Reviewed display names are available in German, Japanese and Traditional Chinese. Other names fall back to the source name; choosing a language does not guarantee a translated city name.
Which countries are covered?
The current catalog covers 36 countries and territories, listed on this page. Coverage and fields vary by country. A place outside the records returns a clear miss, rather than an invented match.
How is City priced?
Each lookup, search or nearby call uses one API request. Optional Deep is available on paid plans and uses the same request.
City API pricing
Put cities in your app.
Your API request allowance is shared across ParseAPI products. Lookup, search and nearby places on every plan. Optional Deep on paid plans.
Free
Start with a free API key.
Room to grow
Choose your capacity on Plans.