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
Highlighted fields: Included on paid plans.
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" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-API-Version: 2.2.0"Example response
Highlighted fields: Included on paid plans.
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.
Included on paid plans
Population.
In context.
Read the count alongside its place identity. Population, area and elevation stay together in the same response.
Paid plans automatically include available area, elevation and capital status in the same response.
Read the paid 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.
City · Core on every plan
Choose the city
/city/miami?country=US
Miami returns timezone America/New_York and country US. If several places match your input, use search and save the selected city id.
Core fields you can reuse
{
"country": "US",
"latitude": 25.775163,
"longitude": -80.208615,
"timezone": "America/New_York"
}Continue with the fields you need. Each follow-up is a separate call.
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, 'X-API-Version': '2.2.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.
// Each follow-up keeps its own success or failure result.
const [time, holidays, weather] = await Promise.allSettled([
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?v=c18e1976f5b8"
data-key="parse_public_YOUR_KEY" data-parse-version="2.2.0" 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
- nameLink to namestring or null
- City name
- name_localLink to name_localstring or null
- Local-language name, null when absent or identical to name
- typeLink to typestring or null
- What the place is in its own country's words (city, town, commune, ward)
- countyLink to countystring or null
- County code the city sits in (US FIPS, FR INSEE, GB GSS)
- county_nameLink to county_namestring or null
- County name
- stateLink to statestring or null
- State or province code
- state_nameLink to state_namestring or null
- State or province name
- countryLink to countrystring or null
- ISO2 country code
- country_nameLink to country_namestring or null
- Country name
- latitudeLink to latitudenumber or null
- Latitude
- longitudeLink to longitudenumber or null
- Longitude
- timezoneLink to timezonestring or null
- Timezone identifier
- distanceLink to distancenumber
- Kilometers from query point (coords and nearby)
- distance_miLink to distance_minumber
- Miles from query point (coords and nearby)
- grainLink to grainstring or null
- Reviewed geographic layer, returned with hierarchy=true; null when unreviewed
- parentLink to 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
- idLink to idstring or null
- Stable city id (city_...). Fetch again at /city/id/{id}
Paid fields
- capital_ofLink to capital_ofstring or null
- country when it is a national capital, state when it is a state or region capital, null otherwise
- elevationLink to elevationinteger or null
- Elevation in meters at the city center
- elevation_ftLink to elevation_ftinteger or null
- Elevation in feet
- populationLink to populationinteger or null
- Population
- population_observed_onLink to population_observed_onstring
- Exact observation date for a reviewed count at this place layer; omitted for legacy undated counts
- population_basisLink to population_basisstring
- Published counting basis, such as household registration or usual residence; omitted when unreviewed
- areaLink to areanumber or null
- Total area in km² (land + water, or the official total)
- land_areaLink to land_areanumber or null
- Land area in km² (null when the source publishes total only)
- water_areaLink to 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. Paid plans include 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. Paid plans automatically include available profile detail in 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. Paid plans include available profile detail automatically.
Free
Start with a free API key.
Room to grow
Choose your capacity on Plans.