Metadata-Version: 2.4
Name: django-vi-address
Version: 1.0.1
Summary: A Django app to migrate Vietnam address.
Home-page: https://github.com/tinhpb9x/django-vi-address
Author: Tinh Pham Ba
Author-email: tinhpb9x@gmail.com
License: BSD-3-Clause
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: django
Requires-Dist: djangorestframework
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

django-vi-address
=================

A Django app providing models, a REST API, and a data-import management
command for Vietnam's administrative divisions — provinces/cities and
wards.

Since July 1, 2025, Vietnam officially abolished the district (huyện)
administrative level nationwide (Resolution No. 1656/NQ-UBTVQH15 and
related merger resolutions). Starting with version 1.0.0, this package
reflects that change end-to-end: the hierarchy is now **province/city →
ward** (previously province/city → district → ward), and the bundled
dataset covers the post-merger 34 provinces/cities.

If you need the old three-level (province → district → ward) hierarchy,
pin to ``django-vi-address<1.0.0``.

Features
--------
- ``City`` and ``Ward`` models — ``Ward.parent_code`` points directly to
  its parent ``City``.
- Read-only REST API (Django REST Framework) to list cities and fetch a
  city with all of its wards.
- An ``insert_data`` management command that loads the bundled JSON
  dataset into your database.
- Each ``Ward`` carries a ``note`` field describing its merger/rename
  history, sourced from the official resolution data.

Requirements
------------
Python >= 3.6

Installation
------------
1. Create a new project::

    mkdir new_project && cd new_project

2. Create a virtual environment::

    virtualenv venv
    source venv/bin/activate

3. Install the package::

    pip install django-vi-address

Quick start
-----------

1. Add ``rest_framework`` and ``vi_address`` to ``INSTALLED_APPS``::

    INSTALLED_APPS = [
        ...
        'rest_framework',  # new
        'vi_address',      # new
        ...
    ]

2. Include the ``vi_address`` URLconf in your project's ``urls.py``::

    # your_project/urls.py
    from django.urls import path, include

    urlpatterns = [
        ...
        path('api/address/', include('vi_address.urls')),
        ...
    ]

3. Run migrations::

    python manage.py migrate

4. Load the data::

    python manage.py insert_data

API
---
- ``GET /api/address/cities`` — list all provinces/cities.
- ``GET /api/address/city/{city_id}`` — retrieve a city with its wards.

Changelog
---------
See `CHANGELOG.rst <https://github.com/tinhpb9x/django-vi-address/blob/master/CHANGELOG.rst>`_.

License
-------
BSD-3-Clause
