Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Countries and cities of the world for Django projects
Python HTML
Tree: f0355684f7

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Place models and worldwide place data for Django

django-cities provides you with place related models (eg. Country, Region, City) and data (from GeoNames) that can be used in your django projects.

Authored by Ben Dowling, and some great contributors.


Your database must support spatial queries, see the GeoDjango documentation for details and setup instructions.


Either clone this repository into your project, or install with pip install django-cities

You'll need to add cities to INSTALLED_APPS in your projects file:


Then run ./ syncdb to create the required database tables, and ./ cities --import=all to import all of the place data. NOTE: This can take a long time.


There are various optional configuration options you can set in your

# Override the default source files and URLs
    'city': {
       'filename': '',
       'urls':     [''+'{filename}']

# Localized names will be imported for all ISO 639-1 locale codes below.
# 'und' is undetermined language data (most alternate names are missing a lang tag).
# See
# 'LANGUAGES' will match your language settings

# Postal codes will be imported for all ISO 3166-1 alpha-2 country codes below.
# See cities.conf for a full list of country codes.
# See

# List of plugins to process data during import
    'cities.plugin.postal_code_ca.Plugin',  # Canada postal codes need region codes remapped to match geonames


This repostitory contains an example project which lets you browse the place hierarchy. See the example directory. Below are some small snippets to show you the kind of things that are possible:

# Find the 5 most populated countries in the World
>>> Country.objects.order_by('-population')[:5]
[<Country: China>, <Country: India>, <Country: United States>, <Country: Indonesia>, <Country: Brazil>]

# Find what country the .ly TLD belongs to
>>> Country.objects.get(tld='ly')
<Country: Libya>

# 5 Nearest cities to London
>>> london = City.objects.filter(country__name='United Kingdom').get(name='London')
>>> nearest = City.objects.distance(london.location).exclude('distance')[:5]

# All cities in a state or county
>>> City.objects.filter(country__name="United States", region__name="Texas")
>>> City.objects.filter(country__name="United States", subregion__name="Orange County")

# Get all countries in Japanese preferring official names if available, fallback on ASCII names:
>>> [country.alt_names_ja.get_preferred( for country in Country.objects.all()]

# Use alternate names model to get Vancouver in Japanese
>>> geo_alt_names[City]['ja'].objects.get_preferred(geo__name='Vancouver', default='Vancouver')

# Get region objects for US postal code:
>>> Region.objects.filter(postal_codes_US__code='90210')
[<Region: California, United States>]

>>> Subregion.objects.filter(postal_codes_US__code='90210')
[<Subregion: Los Angeles County, California, United States>]


The localized names and postal code models/db-tables are created dynamically based on your settings.

Some datasets are very large (> 100 MB) and take time to download / import, and there's no progress display.

Data will only be downloaded / imported if it is newer than your data, and only matching rows will be overwritten.

The cities manage command has options, see --help. Verbosity is controlled through LOGGING.

Something went wrong with that request. Please try again.