Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Countries and cities of the world for Django projects
tree: 55ce86c5cb

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


 django-cities - Place models and data for Django apps

This add-on provides models and commands to import country/region/city data into your database.
The data is pulled from GeoNames and contains:
    - localized names
    - geographical codes
    - postal codes
    - geo-coords
    - population

Your database must support spatial queries, see GeoDjango for setup.

For more information see:

Finding all London boroughs:

>>> london = City.objects.filter(country__name='United Kingdom').get(name='London')
>>> boroughs = District.objects.filter(city=london)

Nearest city to a given geo-coord (longitude, latitude):

>>> City.objects.distance(Point(1, 51)).order_by('distance')[0]
<City: Dymchurch, Kent, United Kingdom>

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]

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')

Gather names of Tokyo from all CITIES_LOCALES:

>>> [name for locale in cities.conf.settings.locales
        for name in geo_alt_names[City][locale].objects.filter(geo__name='Tokyo')]

Get all postal codes for Ontario, Canada (only first 3 letters available due to copyright restrictions):

>>> postal_codes['CA'].objects.filter(region_0_name='Ontario')

Get region objects for US postal code:

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

Get a list of cities in the state of Texas:

>>> City.objects.filter(country__name="United States", region__region_parent__name="Texas")

- Run: python install
- Add/Merge the following into your


    'handlers': {
    'loggers': {
        'cities': {
            'handlers': ['console'],
            'level': 'INFO',

    # Uncomment below to import all cities with population > 1000 (default is > 5000)
    #'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).
# Ref:
CITIES_LOCALES = ['en', 'und']  # + ['LANGUAGES']   # Uncomment to also include languages from your 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.
# Ref:

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

- Sync your database with the new models: ' syncdb'
- Populate or update your database: ' cities'

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.