API reference

The entire database is contained in the dictionary codes.

>>> from gb2260 import *
>>> codes.get(542621) == {
...   'alpha': None,
...   'latitude': 29.6365717,
...   'level': 3,
...   'longitude': 94.3610895,
...   'name_en': 'Nyingchi',
...   'name_pinyin': 'Linzhi',
...   'name_zh': '林芝县',
...   }
True
>>> codes.get(632726)['level']
3

exception gb2260.AmbiguousRegionError

Exception for a lookup that returns multiple results.

exception gb2260.InvalidCodeError

Exception for an invalid code.

exception gb2260.RegionKeyError

Exception for a lookup that returns nothing.

gb2260.isolike(code, prefix='CN-')

Return an ‘ISO 3166-2-like’ alpha code for code.

ISO 3166-2:CN defines codes like “CN-11” for Beijing, where “11” are the first two digits of the GB/T 2260 code, 110000. An ‘ISO 3166-2-like’ alpha code uses the official GB/T 2260 two-letter alpha codes for province-level divisions (e.g. ‘BJ’), and three-letter alpha codes for lower divisions, separated by hyphens:

>>> alpha(130100)
'CN-HE-SJW'

For divisions below level 2, no official alpha codes are provided, so alpha() raises ValueError.

gb2260.level(code)

Return the administrative level of code.

>>> level(110108)
3

For codes not in the database, raises InvalidCodeError.

gb2260.parent(code, parent_level=None)

Return a valid code that is the parent of code.

>>> parent(110108)
110100
>>> parent(110100)
110000

If parent_level is supplied, the parent at the desired level is returned:

>>> parent(110108, 1)
110000

gb2260.split(code)

Return a tuple containing the three parts of code.

>>> split(331024)
(33, 10, 24)

gb2260.within(a, b)

Return True if division a is within (or the same as) division b.

>>> within(331024, 330000)
True
>>> within(331024, 110000)
False
>>> within(331024, 331024)
True

within() does not check that a or b are valid codes that exist in the database.

>>> within(331024, 990000)
False
>>> within(990101, 990000)
True