skip to navigation
skip to content

django-cities 0.3

Place models and worldwide place data for Django

Latest Version:

# django-cities
### 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](


### Requirements

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

### Setup

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.

### Configuration

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.
# You can also specificy 'ALL' to import all postal codes.
# 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

### Examples

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 zip codes near Mountain View, CA
>>> PostalCode.objects.distance(City.objects.get(name='Mountain View', region__name='California').location).order_by('distance')[:5]
[<postalcode: 94040="">, <postalcode: 94041="">, <postalcode: 94043="">, <postalcode: 94024="">, <postalcode: 94022="">]

### Notes

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.  
File Type Py Version Uploaded on Size
django-cities-0.3.tar.gz (md5) Source 2014-02-25 13KB