README

 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:
http://www.coderholic.com/django-cities-countries-regions-cities-and-districts-for-django/


 Examples
=======================
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(id=london.id).order_by('distance')[:5]

Get all countries in Japanese preferring official names if available, fallback on ASCII names:

>>> [country.alt_names_ja.get_preferred(default=country.name) 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")


 Install
=======================
- Run: python setup.py install
- Add/Merge the following into your settings.py:

-----------------------------------------------------------
INSTALLED_APPS = (
    'cities',
)

LOGGING = {
    'handlers': {
        'console':{
            'level':'DEBUG',
            'class':'logging.StreamHandler',
        },
    },
    'loggers': {
        'cities': {
            'handlers': ['console'],
            'level': 'INFO',
        }
    }
}

CITIES_FILES = {
    # Uncomment below to import all cities with population > 1000 (default is > 5000)
    #'city': {
    #   'filename': 'cities1000.zip',
    #   'urls':     ['http://download.geonames.org/export/dump/'+'{filename}']
    #},
}

# Localized names will be imported for all locale codes below.
# 'und' is undetermined language data (most alternate names are missing a lang tag).
# Ref: download.geonames.org/export/dump/iso-languagecodes.txt
CITIES_LOCALES = ['en', 'und']  # + ['LANGUAGES']   # Uncomment to also include languages from your settings

# Postal codes will be imported for all country codes below.
# See cities.conf for a full list of country codes.
# Ref: download.geonames.org/export/dump/countryInfo.txt
CITIES_POSTAL_CODES = ['US','CA']

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

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


 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.