Download World Cities Database

Cities, towns, villages, and hamlets by country

Download a world cities database built from OpenStreetMap, with country-specific files ready for research, data products, and location-based applications.

The files are packaged as NDJSON for efficient processing, with one GeoJSON record per line. Each record includes names, address hierarchy, population when available, centroid coordinates, bounding boxes, OSM identifiers, and optional administrative boundary links.

Use the identifiers with the Geoapify Place Details API for richer geometry, or keep the files offline for your own analysis pipeline.

Download Database

View Schema

Quick answer: Geoapify's World Cities Database is a free, country-based download of localities compiled from OpenStreetMap.

• Coverage: cities, towns, villages, and hamlets, grouped by country.
• Format: ZIP archives with NDJSON files inside; each line is a GeoJSON record.
• Fields: names, address hierarchy, coordinates, bounding boxes, OSM identifiers, population when available, and optional boundary links.
• Use cases: offline locality data for GIS analysis, data products, search indexes, maps, and location-based applications.

Global Cities and Settlements Dataset

We ship the data as country-specific archives using the ISO alpha-2 code. Typical filenames look like us.zip for the United States, ca.zip for Canada, or de.zip for Germany.

Inside each archive you’ll find up to four newline-delimited JSON files, one per settlement tier:

• place-city.ndjson
• place-town.ndjson
• place-village.ndjson
• place-hamlet.ndjson

Download only the country and granularity you need - no planet-scale unzip just to work with one area.

Download Files by Country

The download directory groups the settlement files by country. Choose a ZIP archive, then process the NDJSON file for the settlement level you need.

Direct country archive examples:

• United States: https://www.geoapify.com/data-share/localities/us.zip
• Canada: https://www.geoapify.com/data-share/localities/ca.zip
• Germany: https://www.geoapify.com/data-share/localities/de.zip

We use NDJSON (newline-delimited JSON), which allows you to read large files line by line. Each line contains one GeoJSON record, so you can stream the data efficiently while keeping the geometry and properties in a standard geospatial format.

How we compile the settlement data

We curate the records directly from OpenStreetMap with two complementary passes:

• Settlements (place=*) – we pick up every feature tagged as city, town, village, or hamlet.
• Administrative boundaries – we add polygons tagged as boundary=administrative when they reference the same settlement level (through linked_place, border_type, or place tags) or clearly represent municipal areas via their admin_level.

This approach gives you both the populated place features and the boundaries that frame them.

Heads-up: When we import boundaries we first try to attach them to the matching populated place. If the boundary exists on its own (no place=* partner), we still include it and set inferred_type to the settlement level it represents—city, town, village, or hamlet. That flag tells you how to categorise the record even though the original OSM feature is tagged only as boundary=administrative. Some areas in OSM remain mapped this way, so you may encounter boundary-only rows until local mappers add the corresponding place nodes or ways.

City, Town, Village, and Hamlet Schema

Each GeoJSON record in the download follows the same schema so you can switch between countries without remapping columns:

• name, other_names, and display_name capture the primary and alternate labels for the place.
• address provides the nested administrative hierarchy such as county, state, ISO codes, and country code.
• population contains the crowd-sourced population value when it exists in OSM.
• osm_type, osm_id, and type identify the original OpenStreetMap feature and its settlement level.
• location and bbox store the centroid coordinates and bounding box in [lon, lat] order.
• border links to the matching administrative geometry (single object or array) and inferred_type flags inferred settlement levels when only a boundary is available.

The table below summarises every field:

Here’s what a single record looks like. It shows the US city "Worcester" with the border block that mirrors the same fields for the administrative outline:

Border property explanation

The border field lets you work with both the populated place (place=*) and its matching boundary=administrative geometry without extra lookups. Each entry in border mirrors the top-level schema—name, identifiers, coordinates, and bounding box—so you can reuse the same parsing logic. Depending on the data available in OSM, border can be a single object or an array of objects. When the dataset only has an administrative relation for a settlement, the inferred_type property shows which settlement level we mapped it to.

Below is a sample of U.S. records that illustrates how population, bounding boxes, and administrative borders are bundled together.

Code Samples

Use these examples to connect the download files with common processing tasks: reading NDJSON, filtering places by administrative fields, checking duplicate records, and retrieving the source OpenStreetMap geometry.

Get the original OSM object and its geometry

To retrieve the original OSM object and its geometry, use the Geoapify Place Details API. You'll need the unique identifiers from the dataset, such as osm_id and osm_type, to make requests to the API.

Here is a URL example:

https://api.geoapify.com/v2/place-details?osm_id=62422&osm_type=r&apiKey=YOUR_API_KEY

Compare duplicate city records

Sometimes duplicates appear when multiple OpenStreetMap objects reference the same place. For example, one entry may represent the city boundary, while another describes the city center:

{"name":"Berlin","population":3769962,"osm_type":"relation","osm_id":62422,"type":"administrative","location":[13.3888599,52.5170365],"bbox":[13.088345,52.3382448,13.7611609,52.6755087]}
{"name":"Berlin","population":3769962,"osm_type":"node","osm_id":240109189,"type":"city","location":[13.3888599,52.5170365],"bbox":[13.2288599,52.3570365,13.5488599,52.6770365]}

The first row corresponds to OSM relation 62422, and the second row corresponds to OSM node 240109189.

Filter cities by U.S. state

Use address fields to find all places within one administrative location. Here is a Python code sample for selecting all cities in California:

cities_in_california = [city for city in data if city['address']['state'] == 'California']

Read an NDJSON file in Python

Here's a Python example using pandas and an alternative method with json for reading NDJSON files.

Using pandas:

import pandas as pd

# Read an NDJSON file line by line
data = pd.read_json('place-city.ndjson', lines=True)

Using json:

import json

data = []

# Read an NDJSON file one line at a time
with open("place-city.ndjson") as f:
    for line in f:
        data.append(json.loads(line))

Both methods achieve the same result, allowing you to read NDJSON files into a Python data structure for further processing.

Read an NDJSON file in JavaScript

You can use the readline module to read NDJSON files line by line in Node.js:

const readline = require('readline');
const fs = require('fs');

const data = [];

const readStream = readline.createInterface({
  input: fs.createReadStream('place-village.ndjson')
});

readStream.on('line', (line) => {
  data.push(JSON.parse(line));
});

readStream.on('close', () => {
  console.log(data); // Process the data as needed
});

Copyright and License

The data contained in this dataset is compiled from the OpenStreetMap (OSM) database and is subject to the copyright terms and conditions of OSM contributors.

OpenStreetMap® is open data, licensed under the Open Data Commons Open Database License (ODbL) by the OpenStreetMap Foundation (OSMF).

You are free to copy, distribute, transmit, and adapt the data, as long as you credit OpenStreetMap and its contributors. If you alter or build upon our data, you may distribute the result only under the same license.

Learn More

Continue with practical examples for preparing, enriching, and visualizing the settlement files. These guides show how to turn the download into analysis-ready data, map layers, and broader OpenStreetMap workflows.

Cities, Towns, Villages and Hamlets dataset: How to Use for Data Analysis

Explore the possibilities within our cities, towns, villages, and hamlets dataset through this guide to data analysis. Unlock insights with the help of JavaScript and Python code samples

JavaScript Heatmap Example: A Step-by-Step Tutorial to Build Heatmaps with MapLibre GL

Learn to build interactive US population heatmaps with MapLibre GL in this JavaScript heatmap example tutorial on JSFiddle

3 Ways to Get OpenStreetMap(OSM) Data

OpenStreetMap is the largest geo-database in the world. Learn how to get the OSM data and use it with SQL queries, Overpass API, and Places API

Frequently Asked Questions