Skip to content


Subversion checkout URL

You can clone with
Download ZIP
tree: 03a523db70
Fetching contributors…

Cannot retrieve contributors at this time

145 lines (111 sloc) 4.65 kb

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 this blog post.


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 a list of 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')

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


Get region objects for US postal code:

    [<Region: California, United States>]
    [<Subregion: Los Angeles County, California, United States>]


  • 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.

Jump to Line
Something went wrong with that request. Please try again.