1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
|
Google i18n address
===========================================================================================
|codecov.io| |Circle CI| |PyPi downloads| |requires.io| |PyPi version| |PyPi pythons|
This package contains a copy of `Google's i18n
address <https://chromium-i18n.appspot.com/ssl-address>`_ metadata repository
that contains great data but comes with no uptime guarantees.
Contents of this package will allow you to programatically build address
forms that adhere to rules of a particular region or country, validate
local addresses and format them to produce a valid address label for
delivery.
The package also contains a Python interface for address validation.
Addresses validation
--------------------
The ``normalize_address`` function checks the address and either returns its
canonical form (suitable for storage and use in addressing envelopes) or
raises an ``InvalidAddress`` exception that contains a list of errors.
Address fields
~~~~~~~~~~~~~~
Here is the list of recognized fields:
* ``country_code`` is a two-letter ISO 3166-1 country code
* ``country_area`` is a designation of a region, province or state,
recognized values include official names, designated abbreviations,
official translations and latin transliterations
* ``city`` is a city or town name, recognized values include official names,
official translations and latin transliterations
* ``city_area`` is a sublocality like a district, recognized values include
official names, official translations and latin transliterations
* ``street_address`` is the (possibly multiline) street address
* ``postal_code`` is a postal code or zip code
* ``sorting_code`` is a sorting code
* ``name`` is a person's name
* ``company_name`` is a name of a company or organization
Errors
~~~~~~
Address validation with only country code:
.. code:: python
>>> from i18naddress import InvalidAddress, normalize_address
>>> try:
... address = normalize_address({'country_code': 'US'})
... except InvalidAddress as e:
... print(e.errors)
...
{'city': 'required',
'country_area': 'required',
'postal_code': 'required',
'street_address': 'required'}
With correct address:
.. code:: python
>>> from i18naddress import normalize_address
>>> address = normalize_address({
'country_code': 'US',
'country_area': 'California',
'city': 'Mountain View',
'postal_code': '94043',
'street_address': '1600 Amphitheatre Pkwy'})
>>> print(address)
{'city': 'MOUNTAIN VIEW',
'city_area': '',
'country_area': 'CA',
'country_code': 'US',
'postal_code': '94043',
'sorting_code': '',
'street_address': '1600 Amphitheatre Pkwy'}
Postal code/zip code validation example:
.. code:: python
>>> from i18naddress import InvalidAddress, normalize_address
>>> try:
... address = normalize_address({
... 'country_code': 'US',
... 'country_area': 'California',
... 'city': 'Mountain View',
... 'postal_code': '74043',
... 'street_address': '1600 Amphitheatre Pkwy'})
... except InvalidAddress as e:
... print(e.errors)
...
{'postal_code': 'invalid'}
Address latinization
~~~~~~~~~~~~~~~~~~~~
In some cases it may be useful to display foreign addresses in a more
accessible format. You can use the ``latinize_address`` function to obtain
a more verbose, latinized version of an address.
This version is suitable for display and useful for full text search indexing
but the normalized form is what should be stored in the database and used when
printing address labels.
.. code:: python
>>> from i18naddress import latinize_address
>>> address = {
... 'country_code': 'CN',
... 'country_area': '云南省',
... 'postal_code': '677400',
... 'city': '临沧市',
... 'city_area': '凤庆县',
... 'street_address': '中关村东路1号'}
>>> latinize_address(address)
{'country_code': 'CN',
'country_area': 'Yunnan Sheng',
'city': 'Lincang Shi',
'city_area': 'Lincang Shi',
'sorting_code': '',
'postal_code': '677400',
'street_address': '中关村东路1号'}
It will also return expanded names for area types that normally use codes and
abbreviations such as state names in US:
.. code:: python
>>> from i18naddress import latinize_address
>>> address = {
... 'country_code': 'US',
... 'country_area': 'CA',
... 'postal_code': '94037',
... 'city': 'Mountain View',
... 'street_address': '1600 Charleston Rd.'}
>>> latinize_address(address)
{'country_code': 'US',
'country_area': 'California',
'city': 'Mountain View',
'city_area': '',
'sorting_code': '',
'postal_code': '94037',
'street_address': '1600 Charleston Rd.'}
Address formatting
~~~~~~~~~~~~~~~~~~
You can use the ``format_address`` function to format the address following
the destination country's post office regulations:
.. code:: python
>>> address = {
... 'country_code': 'CN',
... 'country_area': '云南省',
... 'postal_code': '677400',
... 'city': '临沧市',
... 'city_area': '凤庆县',
... 'street_address': '中关村东路1号'}
>>>> print(format_address(address))
677400
云南省临沧市凤庆县
中关村东路1号
CHINA
You can also ask for a latin-friendly version:
.. code:: python
>>> address = {
... 'country_code': 'CN',
... 'country_area': '云南省',
... 'postal_code': '677400',
... 'city': '临沧市',
... 'city_area': '凤庆县',
... 'street_address': '中关村东路1号'}
>>> print(format_address(address, latin=True))
中关村东路1号
凤庆县
临沧市
云南省, 677400
CHINA
Validation rules
~~~~~~~~~~~~~~~~
You can use the ``get_validation_rules`` function to obtain validation data
useful for constructing address forms specific for a particular country:
.. code:: python
>>> from i18naddress import get_validation_rules
>>> get_validation_rules({'country_code': 'US', 'country_area': 'CA'})
ValidationRules(
country_code='US',
country_name='UNITED STATES',
address_format='%N%n%O%n%A%n%C, %S %Z',
address_latin_format='%N%n%O%n%A%n%C, %S %Z',
allowed_fields={'street_address', 'company_name', 'city', 'name', 'country_area', 'postal_code'},
required_fields={'street_address', 'city', 'country_area', 'postal_code'},
upper_fields={'city', 'country_area'},
country_area_type='state',
country_area_choices=[('AL', 'Alabama'), ..., ('WY', 'Wyoming')],
city_type='city',
city_choices=[],
city_area_type='suburb',
city_area_choices=[],
postal_code_type='zip',
postal_code_matchers=[re.compile('^(\\d{5})(?:[ \\-](\\d{4}))?$'), re.compile('^9[0-5]|96[01]')],
postal_code_examples=['90000', '96199'],
postal_code_prefix='')
All known fields
----------------
You can use ``KNOWN_FIELDS`` set, to render optional address fields as hidden
elements of your form:
.. code:: python
>> from i18naddress import get_validation_rules, KNOWN_FIELDS
>> rules = get_validation_rules({'country_code': 'US'})
>> KNOWN_FIELDS - rules.allowed_fields
{'city_area', 'sorting_code'}
Raw i18n data
-------------
Raw data is stored in a dict:
.. code:: python
>>> from i18naddress import load_validation_data
>>> i18n_country_data = load_validation_data()
>>> i18n_country_data['US']
{'fmt': '%N%n%O%n%A%n%C, %S %Z',
'id': 'data/US',
'key': 'US',
'lang': 'en',
'languages': 'en',
'name': 'UNITED STATES',
'posturl': 'https://tools.usps.com/go/ZipLookupAction!input.action',
'require': 'ACSZ',
'state_name_type': 'state',
'sub_keys': 'AL~AK~AS~AZ~AR~AA~AE~AP~CA~CO~CT~DE~DC~FL~GA~GU~HI~ID~IL~IN~IA~KS~KY~LA~ME~MH~MD~MA~MI~FM~MN~MS~MO~MT~NE~NV~NH~NJ~NM~NY~NC~ND~MP~OH~OK~OR~PW~PA~PR~RI~SC~SD~TN~TX~UT~VT~VI~VA~WA~WV~WI~WY',
'sub_names': 'Alabama~Alaska~American Samoa~Arizona~Arkansas~Armed Forces (AA)~Armed Forces (AE)~Armed Forces (AP)~California~Colorado~Connecticut~Delaware~District of Columbia~Florida~Georgia~Guam~Hawaii~Idaho~Illinois~Indiana~Iowa~Kansas~Kentucky~Louisiana~Maine~Marshall Islands~Maryland~Massachusetts~Michigan~Micronesia~Minnesota~Mississippi~Missouri~Montana~Nebraska~Nevada~New Hampshire~New Jersey~New Mexico~New York~North Carolina~North Dakota~Northern Mariana Islands~Ohio~Oklahoma~Oregon~Palau~Pennsylvania~Puerto Rico~Rhode Island~South Carolina~South Dakota~Tennessee~Texas~Utah~Vermont~Virgin Islands~Virginia~Washington~West Virginia~Wisconsin~Wyoming',
'sub_zipexs': '35000,36999~99500,99999~96799~85000,86999~71600,72999~34000,34099~09000,09999~96200,96699~90000,96199~80000,81999~06000,06999~19700,19999~20000,20099:20200,20599:56900,56999~32000,33999:34100,34999~30000,31999:39800,39899:39901~96910,96932~96700,96798:96800,96899~83200,83999~60000,62999~46000,47999~50000,52999~66000,67999~40000,42799~70000,71599~03900,04999~96960,96979~20600,21999~01000,02799:05501:05544~48000,49999~96941,96944~55000,56799~38600,39799~63000,65999~59000,59999~68000,69999~88900,89999~03000,03899~07000,08999~87000,88499~10000,14999:06390:00501:00544~27000,28999~58000,58999~96950,96952~43000,45999~73000,74999~97000,97999~96940~15000,19699~00600,00799:00900,00999~02800,02999~29000,29999~57000,57999~37000,38599~75000,79999:88500,88599:73301:73344~84000,84999~05000,05999~00800,00899~20100,20199:22000,24699~98000,99499~24700,26999~53000,54999~82000,83199:83414',
'sub_zips': '3[56]~99[5-9]~96799~8[56]~71[6-9]|72~340~09~96[2-6]~9[0-5]|96[01]~8[01]~06~19[7-9]~20[02-5]|569~3[23]|34[1-9]~3[01]|398|39901~969([1-2]\\d|3[12])~967[0-8]|9679[0-8]|968~83[2-9]~6[0-2]~4[67]~5[0-2]~6[67]~4[01]|42[0-7]~70|71[0-5]~039|04~969[67]~20[6-9]|21~01|02[0-7]|05501|05544~4[89]~9694[1-4]~55|56[0-7]~38[6-9]|39[0-7]~6[3-5]~59~6[89]~889|89~03[0-8]~0[78]~87|88[0-4]~1[0-4]|06390|00501|00544~2[78]~58~9695[0-2]~4[3-5]~7[34]~97~969(39|40)~1[5-8]|19[0-6]~00[679]~02[89]~29~57~37|38[0-5]~7[5-9]|885|73301|73344~84~05~008~201|2[23]|24[0-6]~98|99[0-4]~24[7-9]|2[56]~5[34]~82|83[01]|83414',
'upper': 'CS',
'zip': '(\\d{5})(?:[ \\-](\\d{4}))?',
'zip_name_type': 'zip',
'zipex': '95014,22162-1010'}
>>> i18n_country_data['US/CA']
{'id': 'data/US/CA',
'key': 'CA',
'lang': 'en',
'name': 'California',
'zip': '9[0-5]|96[01]',
'zipex': '90000,96199'}
Used with Django form
---------------------
Django forms will return only required address fields in ``form.cleaned_data`` dict. So addresses in the database will be normalized.
.. code:: python
from django import forms
from i18naddress import InvalidAddress, normalize_address, get_validation_rules
class AddressForm(forms.Form):
COUNTRY_CHOICES = [
('PL', 'Poland'),
('AE', 'United Arab Emirates'),
('US', 'United States of America')]
ERROR_MESSAGES = {
'required': 'This field is required',
'invalid': 'Enter a valid name'}
name = forms.CharField(required=True)
company_name = forms.CharField(required=False)
street_address = forms.CharField(required=False)
city = forms.CharField(required=False)
city_area = forms.CharField(required=False)
country_code = forms.ChoiceField(required=True, choices=COUNTRY_CHOICES)
country_area = forms.CharField(required=False)
postal_code = forms.CharField(required=False)
def clean(self):
clean_data = super(AddressForm, self).clean()
validation_rules = get_validation_rules(clean_data)
try:
valid_address = normalize_address(clean_data)
except InvalidAddress as e:
errors = e.errors
valid_address = None
for field, error_code in errors.items():
if field == 'postal_code':
examples = validation_rules.postal_code_examples
msg = 'Invalid value, use fomat like %s' % examples
else:
msg = ERROR_MESSAGES[error_code]
self.add_error(field, msg)
return valid_address or clean_data
.. image:: https://ga-beacon.appspot.com/UA-10159761-14/mirumee/google-i18n-address?pixel
.. |codecov.io| image:: https://img.shields.io/codecov/c/github/mirumee/google-i18n-address.svg
:target: https://codecov.io/github/mirumee/google-i18n-address?branch=master
.. |Circle CI| image:: https://img.shields.io/circleci/project/mirumee/google-i18n-address.svg
:target: https://circleci.com/gh/mirumee/google-i18n-address/tree/master
.. |PyPi downloads| image:: https://img.shields.io/pypi/dm/google-i18n-address.svg
:target: https://pypi.python.org/pypi/google-i18n-address
.. |PyPi pythons| image:: https://img.shields.io/pypi/pyversions/google-i18n-address.svg
:target: https://pypi.python.org/pypi/google-i18n-address
.. |PyPi version| image:: https://img.shields.io/pypi/v/google-i18n-address.svg
:target: https://pypi.python.org/pypi/google-i18n-address
.. |GitHub| image:: https://img.shields.io/github/stars/mirumee/google-i18n-address.svg?style=social
:target: https://github.com/mirumee/google-i18n-address
.. |requires.io| image:: https://img.shields.io/requires/github/mirumee/google-i18n-address.svg
:target: https://requires.io/github/mirumee/google-i18n-address/requirements/?branch=master
|
