moskytw / zipcodetw

Find Taiwan ZIP code by address fuzzily.

The ZIP Code Finder for Taiwan

This package lets you find ZIP code by address in Taiwan.

The main features:

1. Fast. It builds ZIP code index by tokenization.
2. Gradual. It returns partial ZIP code rather than noting when address is not detailed enoguh.
3. Stand-alone. It depends on nothing.

Usage

Find ZIP code gradually:

>>> import zipcodetw
>>> zipcodetw.find('臺北市')
u'1'
>>> zipcodetw.find('臺北市信義區')
u'110'
>>> zipcodetw.find('臺北市信義區市府路')
u'110'
>>> zipcodetw.find('臺北市信義區市府路1號')
u'11008'

After v0.3, you even can find ZIP code like:

>>> zipcodetw.find('松山區')
u'105'
>>> zipcodetw.find('秀山街')
u''
>>> zipcodetw.find('台北市秀山街')
u'10042'

Installation

It is available on PyPI:

$ sudo pip install zipcodetw

Just install it and have fun. :)

Build Index Manually

If you install it by pip or python setup.py install, a ZIP code index will be built automatically. But if you want to use it from source code, you have to build an index manually:

$ python -m zipcodetw.builder

Data

The ZIP code directory is provided by Chunghwa Post, and is available from: http://www.post.gov.tw/post/internet/Download/all_list.jsp?ID=2201#dl_txt_s_A0206

Changelog

v0.6.5

1. Updated to the 3+3 v2102.01 data.
2. Fixed a Python 3 bug, maybe.

v0.6.2–0.6.4

1. A black hole ate the logs.

v0.6.1

1. Fixed the py2 py3 compatibility. Thanks the contribution from Poren Chiang and Ryan.

v0.6

1. Updated the data to 2014/12.

v0.5.7

1. Fixed a rarely issue that causes IndexError.

v0.5.6

1. Reverted removing insignificant tokens introduced in v0.5.4.
2. It now handles insignificant tokens; and
3. redundant units in the finding logic (directory.find).
4. Allowed number token ends without unit.
5. Now address.tokens is a list.

v0.5.5

1. Fixed a gradual matching issue causing some wrong results.

v0.5.4

1. Removed the token whose unit is insignificant automatically.

v0.5.3

1. Fixed and simplified the matching logic for address tail.
2. Refined the index building logic.

v0.5.2

1. Fixed the issue while it was running in multi-threaded environment.
2. Added a new argument, keep_alive, for the Directory class.

v0.5.1

1. Refined the code slightly.

v0.5

1. It now builds a ZIP code index when you install it; so
2. the package size is 12.5x smaller.
3. The internal API is better now.

v0.4

1. It now shipped with an index compiled in SQLite; so
2. initiation time is ~680x faster, i.e. ~30ms each import; and
3. zipcodetw.find is ~1.9x slower, i.e. ~2ms each call; and
4. has bigger package size.
5. All code was moved into zipcodetw package.
6. zipcodetw.find now returns unicode instead of string.

v0.3

1. It builds full index for middle tokens; and
2. also normalizes Chinese numerals now!
3. zipcodetw.find is ~1.06x faster.
4. But initiation time increases to ~1.7x.

v0.2

1. zipcodetw.find is 8x faster now!
2. It has a better tokenizing logic; and
3. a better matching logic for sub-number now.
4. zipcodetw.find_zipcodes was removed.
5. Internal API was changed a lot.
6. The tests are better now.

zipcodetw's Issues

Remove unicodecsv from dependency for Python 3+

Currently, new installations in a clean virtualenv on Python 3.9.7 would result in the following error:

    File "/private/var/folders/…/zipcodetw/builder.py", line 23, in build
      dir_.load_chp_csv(csv_f)
    File "/private/var/folders/…/zipcodetw/util.py", line 317, in method_wrapper
      retval = method(self, *args, **kargs)
    File "/private/var/folders/…/zipcodetw/util.py", line 340, in load_chp_csv
      for row in csv.reader(lines_iter):
    File "/Users/…/zipcode_test/venv/lib/python3.9/site-packages/unicodecsv/py3.py", line 55, in __next__
      return self.reader.__next__()
    File "/Users/…/zipcode_test/venv/lib/python3.9/site-packages/unicodecsv/py3.py", line 51, in <genexpr>
      f = (bs.decode(encoding, errors=errors) for bs in f)
  AttributeError: 'str' object has no attribute 'decode'
  ----------------------------------------

Running pip remove unicodecsv && python -m zipcodetw.builder fixed the issue.

It appears that unicodecsv has been abandoned as in jdunck/python-unicodecsv#92, and thus no further maintenance are done for the package.

We could either:

• drop the support for Python 2.7,
• use the suggested csv backport from Python 3, or
• specify unicodecsv as our dependency only when Python version < 3 as shown in PEP 0508.

The last one should be the easiest mitigation. Please let me know if a PR is preferred over issues.

台北市復興南路二段 -> returns 10 (instead of 106)

復興南路二段 is entirely in 大安區, so a better result would be 106 instead of 10.

I can see a few pull requests on level 1 token but I am not sure they are related or not.

sqlite3.OperationalError: unable to open database file

When I was running on .py file, everything went great. However, after converting my .py to .exe and executing the .exe file, it pops out the error message.

File "site-packages\zipcodetw\util.py", line 313, in method_wrapper
sqlite3.OperationalError: unable to open database file

Is there any solution?

苗栗縣苗栗市聯大路2號 -> return 360 (instead of 36063)

剛好測到這特殊測資，就來開 Issue 了 👍

Any upgrade plan for 3+3 postal code?

https://www.post.gov.tw/post/internet/Postal/index.jsp?ID=208

臺中市南區興大路145號 -> returns 4024 (instead of 40227)

(前面的 issue 都是這種格式我就照抄了XD)

這是中興大學的地址，興大路在南區的部份只有它不是4024開頭，40227似乎被規則忽略了QQ

.

execute fail on colab

Hi,
I try to use below code on colab:

try:
import zipcodetw
except ImportError:
!pip install zipcodetw
import zipcodetw

zipcodetw.find('臺北市信義區市府路1號')

but colab shows "util.py line 363, OperationalError: no such table: precise"
Is any way to work on colab?
Thanks.

more debug message:
Looking in indexes: https://pypi.org/simple, https://us-python.pkg.dev/colab-wheels/public/simple/
Collecting zipcodetw
Downloading zipcodetw-0.6.8.tar.gz (592 kB)
|████████████████████████████████| 592 kB 7.7 MB/s
Requirement already satisfied: six in /usr/local/lib/python3.7/dist-packages (from zipcodetw) (1.15.0)
Collecting unicodecsv
Downloading unicodecsv-0.14.1.tar.gz (10 kB)
Building wheels for collected packages: zipcodetw, unicodecsv
Building wheel for zipcodetw (setup.py) ... done
Created wheel for zipcodetw: filename=zipcodetw-0.6.8-py3-none-any.whl size=610897 sha256=8e8739c0bd79c942aaf817780ebf89acc61ad3d7a90bcd0c81cf3bd47b41cbb7
Stored in directory: /root/.cache/pip/wheels/37/03/5b/638651b1773a38a94b3a63284267f5bf248af9954dc617f8cd
Building wheel for unicodecsv (setup.py) ... done
Created wheel for unicodecsv: filename=unicodecsv-0.14.1-py3-none-any.whl size=10768 sha256=84c4ba5866616b0e6f7d2821a0cfce99c4dcd26e8a3a178974cdcf096aeb943d
Stored in directory: /root/.cache/pip/wheels/1a/f4/8a/a5024fb77b32ed369e5c409081e5f00fbe3b92fdad653f6e69
Successfully built zipcodetw unicodecsv
Installing collected packages: unicodecsv, zipcodetw
Successfully installed unicodecsv-0.14.1 zipcodetw-0.6.8

OperationalError Traceback (most recent call last)
in ()
5 import zipcodetw
6
----> 7 zipcodetw.find('臺北市信義區市府路1號')

2 frames
/usr/local/lib/python3.7/dist-packages/zipcodetw/util.py in get_rule_str_zipcode_pairs(self, addr_str)
361 from precise
362 where addr_str = ?;
--> 363 ''', (addr_str,))
364
365 return self.cur.fetchall()

OperationalError: no such table: precise

Installation problem: No module named six

I tried to install zipcodetw, however, the installation failed due to No module named 'six' even if there is six in my requirements.txt. The code causing the problem is at line 7 of util.py. Is there any solution?