Top-ranked cities closest to a reference city within a tier.

---

Overview

Returns up to three top-ranked cities closest to a given reference city within a specified population tier. Cities are pre-ranked into four tiers by the rankcities management command: TOP_10 (the ten largest cities globally), TOP_100, TOP_1K, and TOP_10K. Useful for surfacing the nearest major cities to a user's location — for example, finding the closest top-100 city to a small town for display in a regional context or travel application.

---

Request parameters

Name	Type	In	Required	Description	Example
city_slug	String	Body	Yes	Slug of a city record. Obtain valid city slugs from the city list, nearest, or search endpoints.
top	Choice	Body	Yes	Population tier for top-city queries. One of: 0 (TOP_10 — ten largest cities globally), 1 (TOP_100), 2 (TOP_1K), 3 (TOP_10K). Set by the rankcities management command.

---

Response fields

Name	Type	Nullable	Description	Example
results	Array	—	Array of up to three top-ranked cities within the requested tier, closest to the reference city.
results[].admin1	String	—	Region/state/province code (admin level 1).	BC
results[].admin1_id	Integer	—	Primary key of the region record.	75
results[].city_id	Integer	—	Alias for the city primary key, provided for consistency with other endpoints.	5969782
results[].continent_id	Integer	—	Primary key of the continent record.	2
results[].country_id	Integer	—	Primary key of the country record.	38
results[].country_iso	String	—	ISO 3166-1 alpha-2 code of the country.	CA
results[].country_name	String	—	Full name of the country.	Canada
results[].distance	Float	—	Distance from the query point to this city in kilometres, rounded to one decimal place.	3.7
results[].id	Integer	—	Primary key of the city.	5969782
results[].lat	String	Yes	Latitude of the city in decimal degrees.	48.4284
results[].lon	String	Yes	Longitude of the city in decimal degrees.	-123.3648
results[].name	String	—	Name of the city.	Victoria
results[].slug	String	—	URL-friendly city name.	victoria