https://secure.travis-ci.org/yourlabs/django-cities-light.png?branch=master https://pypip.in/d/django-cities-light/badge.png https://pypip.in/v/django-cities-light/badge.png

django-cities-light – Simple django-cities alternative

This add-on provides models and commands to import country, region/state, and city data in your database.

The data is pulled from GeoNames and contains cities, regions/states and countries.

Spatial query support is not required by this application.

This application is very simple and is useful if you want to make a simple address book for example. If you intend to build a fully featured spatial database, you should use django-cities.

Requirements:

  • Python 2.7 or 3.3,
  • Django 1.4 or 1.5 or 1.6,
  • PostgreSQL or SQLite.
  • django-south is optionnal, but recommended.

MySQL support was dropped on 2.x.x because it stopped working. It is supported again in 3.x.x, which uses django.db.transaction.atomic, which requires Django >= 1.6.

Upgrade

See CHANGELOG.

Installation

Install django-cities-light:

pip install django-cities-light

Or the development version:

pip install -e git+git@github.com:yourlabs/django-cities-light.git#egg=cities_light

Add cities_light to your INSTALLED_APPS.

Now, run syncdb, it will only create tables for models that are not disabled:

./manage.py syncdb

Note that this project supports django-south. It is recommended that you use south too else you’re on your own for migrations/upgrades.

Danger

Since version 2.4.0, django-cities-light uses django migrations by default. This means that django-south users should add to settings:

SOUTH_MIGRATION_MODULES = {
    'cities_light': 'cities_light.south_migrations',
}

Data update

Finally, populate your database with command:

./manage.py cities_light

This command is well documented, consult the help with:

./manage.py help cities_light

FAQ

MySQL errors with special characters, how to fix it ?

The cities_light command is continuously tested on travis-ci on all supported databases: if it works there then it should work for you.

If you’re new to development in general, you might not be familiar with the concept of encodings and collations. Unless you have a good reason, you must have utf-8 database tables. See MySQL documentation for details.

We’re pointing to MySQL documentations because PostgreSQL users probably know what UTF-8 is and won’t have any problem with that.

Some data fail to import, how to skip them ?

GeoNames is not perfect and there might be some edge cases from time to time. We want the cities_light management command to work for everybody so you should open an issue in GitHub if you get a crash from that command.

However, we don’t want you to be blocked, so keep in mind that you can use Signals like cities_light.city_items_pre_import, cities_light.region_items_pre_import, cities_light.country_items_pre_import, to skip or fix items before they get inserted in the database by the normal process.

Indices and tables