← Back to docs
endpoints ◀ ▶
POST locci/geo/city/top/

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

Locci Geography

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