City Types

Every city record carries an optional type field describing what kind of place it is. The value is inherited from the upstream GeoNames feature classification.

Building against the API? Filter server-side with ?kind= on Get Cities by Country or Get Cities by State instead of applying a type exclusion list yourself. It is not a drop-in swap: ?kind=settlement is stricter than the exclusion list further down this page, and ?kind=settlement,section,unknown is the closest match. That manual filtering is for teams running their own copy of the raw database outside the API.

The type field mixes two ideas — what a place is (city, town, village) and what administrative role it fills (adm2, county, parish). The same place can be tagged either way. For example, Dallas is adm2 because it is the seat of Dallas County, and major Australian cities are adm1 because they are seats of state-level governments.

The `kind` Field

Get Cities by Country and Get Cities by State also return a derived kind field — a simplified classification computed server-side from type, so you don’t have to memorize which of the 35 raw values count as real places. Other endpoints that return city records do not include it. kind is one of four values:

`kind`	Meaning
`settlement`	An actual populated place — city, town, village, or similar
`administrative`	A governed administrative division that is not itself a settlement (county, province, regency, and similar)
`section`	A suburb or district of a larger city (the `section` type)
`unknown`	Neither a live settlement nor a governed administrative area — defunct or unclassified entries, including `null` and any `type` value not yet in the mapping

The administrative vs. unknown split is this project’s own interpretation layered on top of the source data — the upstream countries-states-cities-database project (and the GeoNames classification it inherits from) does not define a 4-way split like this itself. We separate genuine administrative divisions (county, province, regency, and similar) from defunct or non-place entries (abandoned, historical, religious, and similar) so that administrative only contains types you’d reasonably call a governed area — not a ghost town or a place of worship.

null types and any type value not yet in our mapping default to kind: unknown. Read unknown as not classified, not as not a place — the bucket holds both defunct entries (abandoned, historical, destroyed, religious, historical_capital) and the 1,900 rows that carry no type at all.

Use ?kind=settlement (or any comma-separated combination, e.g. ?kind=settlement,section) on Get Cities by Country or Get Cities by State to filter server-side. kind is available on every plan, including Community and Starter — no tier upgrade required. Raw type filtering (?type=) is also available but requires a Supporter+ plan, matching the existing type field’s tier gate — on a lower plan the request is rejected with a 400 error rather than being ignored.

All Type Values

There are 35 distinct values. The counts below come from the upstream TYPE_FIELD.md reference, snapshotted on 2026-05-24, and add up to 156,025 rows. Treat them as approximate: they drift as the data changes, so they do not match the 153,765+ city total quoted elsewhere in these docs, which is the upstream project’s README figure counted at a different time. The Kind column shows the kind value derived from each type — see above for what each value means.

`type`	Count	Kind	Meaning
`city`	96,098	`settlement`	Actual city
`adm2`	20,796	`settlement`	2nd-order admin division — usually a real city that is also a county/district seat
`adm3`	15,774	`settlement`	Mostly real municipalities/communes tagged with their admin role
`section`	5,346	`section`	Suburbs and districts of larger cities
`county`	4,409	`administrative`	County-level admin unit — not a settlement
`adm4`	3,909	`settlement`	Similar mix to `adm3`
`adm1`	3,505	`settlement`	1st-order admin division — usually a state/region seat (e.g. major Australian cities)
`district`	2,381	`settlement`	District-level populated place
(null)	1,900	`unknown`	No type assigned — see below
`regency`	390	`administrative`	Indonesian kabupaten — admin division
`prefecture`	369	`administrative`	Prefecture-level admin division
`locality`	319	`settlement`	Named populated place
`capital`	281	`settlement`	National or regional capital
`municipality`	209	`settlement`	Municipality
`parish`	80	`administrative`	Louisiana-style parish (= county)
`banner`	52	`administrative`	Inner Mongolia banner — admin division
`town`	48	`settlement`	Town
`province`	36	`administrative`	Province-level admin division
`adm5`	16	`settlement`	5th-order admin division (populated)
`abandoned`	15	`unknown`	Abandoned place
`cities`	13	`settlement`	Data artifact of `city`
`area`	12	`administrative`	Generic administrative area
`village`	10	`settlement`	Village
`historical`	9	`unknown`	Historical place — not a live settlement
`settlement`	9	`settlement`	Settlement
`oblast`	8	`administrative`	Oblast — admin division
`gov_seat`	6	`settlement`	Government seat (populated)
`special municipality`	6	`settlement`	Special municipality
`administrative zone`	5	`administrative`	Administrative zone
`region`	4	`administrative`	Region-level admin division
`destroyed`	3	`unknown`	Destroyed place
`township`	3	`settlement`	Township
`religious`	2	`unknown`	Religious site — not a settlement
`subdistrict`	1	`settlement`	Subdistrict (populated)
`historical_capital`	1	`unknown`	Former capital — not a live settlement

Filtering via Raw SQL/JS/Python (Self-Hosted Data)

Calling the API instead? Use ?kind= — see The kind Field above. It is not a drop-in swap for the exclusion list below. ?kind=settlement is stricter, because the list also keeps the 5,346 section rows and the 1,900 null-type rows. ?kind=settlement,section,unknown is the closest match; it differs only by also returning the ~30 defunct rows the list drops (abandoned, historical, destroyed, religious, historical_capital), which map to unknown too. This section is for teams running their own copy of the raw database outside the API, where no kind field exists.

For use cases like “find the nearest city to a location” or “populate a dropdown” against a self-hosted copy of the data, exclude admin-only and non-place types directly. Use an exclusion list rather than an inclusion list — any new settlement-style value added in the future is kept by default. Exclude these types:

county, regency, prefecture, parish, banner, province, area, oblast,
administrative zone, region, abandoned, historical, destroyed, religious,
historical_capital

SQL

SELECT *
FROM cities
WHERE (
  type IS NULL
  OR type NOT IN (
    'county', 'regency', 'prefecture', 'parish', 'banner', 'province',
    'area', 'oblast', 'administrative zone', 'region',
    'abandoned', 'historical', 'destroyed', 'religious', 'historical_capital'
  )
)
AND latitude IS NOT NULL
AND longitude IS NOT NULL;

type NOT IN (...) evaluates to UNKNOWN for rows where type is NULL, silently dropping them. The explicit type IS NULL OR ... keeps null-type rows. Remove the type IS NULL clause only if you want to exclude them.

JavaScript

const EXCLUDED_TYPES = new Set([
  'county', 'regency', 'prefecture', 'parish', 'banner', 'province',
  'area', 'oblast', 'administrative zone', 'region',
  'abandoned', 'historical', 'destroyed', 'religious', 'historical_capital',
]);

const settlements = cities.filter(
  (c) => !EXCLUDED_TYPES.has(c.type) && c.latitude != null && c.longitude != null
);

Python

EXCLUDED_TYPES = {
  'county', 'regency', 'prefecture', 'parish', 'banner', 'province',
  'area', 'oblast', 'administrative zone', 'region',
  'abandoned', 'historical', 'destroyed', 'religious', 'historical_capital',
}

settlements = [
  c for c in cities
  if c.get('type') not in EXCLUDED_TYPES
  and c.get('latitude') is not None
  and c.get('longitude') is not None
]

Records with No Type

About 1,900 rows have a null type. They are a mix of legitimate places and unclassified entries. For strict settlement queries, the safest signal is the presence of valid coordinates (latitude/longitude not null), and — where available — a non-null population. Via the API, these rows surface with kind: unknown, same as other unclassified entries.

Database Schema

Full cities table definition including the type field.

Multi-Level Territories

How overseas territories and dual-modeled entities affect city queries.

Get Cities by Country

Filter cities by kind or type directly via the API.

Database Documentation

Installation Guides

Support

The `kind` Field

All Type Values

Filtering via Raw SQL/JS/Python (Self-Hosted Data)

SQL

JavaScript

Python

Records with No Type

Database Schema

Multi-Level Territories

Get Cities by Country

​The kind Field

​All Type Values

​Filtering via Raw SQL/JS/Python (Self-Hosted Data)

​SQL

​JavaScript

​Python

​Records with No Type

​Related

Database Schema

Multi-Level Territories

Get Cities by Country

The `kind` Field

All Type Values

Filtering via Raw SQL/JS/Python (Self-Hosted Data)

SQL

JavaScript

Python

Records with No Type

Related