django-cities-teryt 1.0.1
Polish region and city data for Django.
License: MIT
Keywords: django cities teryt gus provinces counties municipalities villages districts

===================
django-cities-teryt
===================

Polish region and city data for Django.

This app provides models, admin integration and commands to import region and city data in your database.

The data is pulled from `TERYT <http://bip.stat.gov.pl/en/teryt/>`_ database
(National Official Register of the Territorial Division of the Country). TERYT is maintained by
Polish Central Statistical Office (`GUS <http://stat.gov.pl/en/>`_)

Database contains:
 - provinces
 - counties
 - municipalities
 - villages
 - cities
 - city districts

Installation
------------

Install django-cities-teryt

.. code:: bash

    pip install django-cities-teryt

Or dev version

.. code:: bash

    pip install -e git+git@github.com:lukaszbanasiak/django-cities-teryt.git#egg=cities_teryt

Add ``cities_teryt`` to your ``INSTALLED_APPS``

.. code:: python

    INSTALLED_APPS = (
        ...
        'cities_teryt',
    )

Now, run ``syncdb``, it will only create tables for models

.. code:: bash

    ./manage.py syncdb

Configuration
-------------

1. Download ``SIMC`` and ``TERC`` xml files from TERYT website http://www.stat.gov.pl/broker/access/prefile/listPreFiles.jspa and save them to one directory.
2. Setup in your ``settings.py`` full path to above directory

.. code:: python

    # Default directory is `import` dir in `django-cities-teryt` app directory
    CITIES_TERYT_IMPORT_DIR = '/path/to/dir'

Importing data
--------------

To populate your database with all TERYT data use command

.. code:: bash

    ./manage.py cities_teryt --data all --import

To remove data use command

.. code:: bash

    ./manage.py cities_teryt --data all --flush

To operate on specific type of data enumerate them after ``--data`` argument

.. code:: bash

    ./manage.py cities_teryt --data province, county, municipality --import
    ./manage.py cities_teryt --data city, village, district --flush

Notice
^^^^^^
Data have relations so it's best to import everything.
Data are large and take time to import (there's no progress display).
Verbosity is controlled through LOGGING.

Examples
--------

Get ``City`` by name

.. code:: python

    >>> City.objects.get(name='Swarzędz')
    <City: Swarzędz (0971502)>

To get name of ``Municipality`` of this City we can use ``parent`` method or call directly ``municipality`` attrib

.. code:: python

    >>> City.objects.get(name='Swarzędz').parent
    <Municipality: Swarzędz (302116)>
    >>> City.objects.get(name='Swarzędz').municipality
    <Municipality: Buk (302103)>
    >>> Municipality.objects.get(city__name='Swarzędz')
    <Municipality: Swarzędz (302116)>

In this way we can get also ``Province`` or ``County``

.. code:: python

    >>> City.objects.get(name='Swarzędz').province
    <Province: wielkopolskie (30)>
    >>> Province.objects.get(city__name='Swarzędz')
    <Province: wielkopolskie (30)>

... or even ``Districts``

.. code:: python

    >>> c = City.objects.get(name='Swarzędz')
    >>> c.district_set.all()
    [<District: Nowa Wieś (0971519)>, <District: Zieleniec (0971525)>]
    >>> District.objects.filter(city=c)
    [<District: Nowa Wieś (0971519)>, <District: Zieleniec (0971525)>]

List all ``Cities`` in the same ``County``

.. code:: python

    >>> County.objects.get(city__name='Swarzędz').city_set.all()
    [<City: Buk (0970520)>, <City: Murowana Goślina (0971152)>, <City: Kostrzyn (0970885)>, <City: Mosina (0971057)>, <City: Pobiedziska (0971287)>, <City: Puszczykowo (0971376)>, <City: Kórnik (0970922)>, <City: Swarzędz (0971502)>, <City: Luboń (0970974)>, <City: Stęszew (0971494)>]

Get pretty display name

.. code:: python

    # Village, Municipality, County, Province
    >>> print Village.objects.get(name='Kaczkowo', province__name='wielkopolskie').get_display_name()
    Kaczkowo, Rydzyna, leszczyński, wielkopolskie
    # `Municipality` and `County` for "Poznań" is the same so we got only `City` and `Province` name
    >>> print City.objects.get(name='Poznań').get_display_name()
    Poznań, wielkopolskie

Requirements
------------

See ``requirements.txt``