Python API v1

Installation

Latest Geobaza Python API version is 1.0.3.

Official releases of Geobaza Lite are available via PyPi or on the download page: http://geobaza.ru/download/

Installation using pip or easy_install.

pip install geobaza

To install manually: download distribution archive, extract it, and execute python setup.py install.

curl -OJ http://geobaza.ru/download/latest/python
unzip geobaza-lite-python-api-x.x.zip
cd geobaza-x.x/
python setup.py install

System Requirements

Python 2.5+. Python 3 is not supported at this time.

Dependencies

For Geobaza correct work, the simplejson package is required. It is available via PyPi.

Usage

Getting Started

>>> from geobaza import GeobazaQuery
>>> query = GeobazaQuery()

>>> # Headers: API version, binary file release version, build time
>>> query.headers.release
'5.0.8'
>>> query.headers.build_date.isoformat()
'2011-09-20T15:52:07'
>>> query.headers.api_version
5
>>> query.headers.build_timestamp
1316519527

Obtaining Single Object

If you want to get only one specific geographical object (for example, to save its identifier in statistics system database), use get() method.

>>> obj = query.get('80.250.189.254')

>>> obj
<Locality: Velikiy Novgorod>

>>> # Object properties
>>> obj.name
u'Velikiy Novgorod'
>>> obj.type
u'locality'

>>> # Unique ID
>>> obj.id
5069

>>> # Coordinates
>>> obj.geography.center.latitude
58.515999999999998
>>> obj.geography.center.longitude
31.283000000000001

>>> # Parent object
>>> obj.parent
<Region: Novgorod Region>

Obtaining Full Path

To get full path to the geographical object including country and regions, use get_path() method. Its execution will take more resources and time than get() method.

>>> path = query.get_path('80.250.189.254')

>>> path
<Geobaza: [<Country: Russian Federation>, <Region: North West Federal Region>, +2 objects]>

>>> # Iteration over objects list
>>> for obj in path:
...     print obj
...
<Country: Russian Federation>
<Region: North West Federal Region>
<Region: Novgorod Region>
<Locality: Velikiy Novgorod>

>>> # Country
>>> path.country
<Country: Russian Federation>

>>> # Regions
>>> path.regions
<Geobaza: [<Region: North West Federal Region>, <Region: Novgorod Region>]>

>>> # Localities
>>> path.localities
<Geobaza: [<Locality: Velikiy Novgorod>]>

Objects Properties

Common

>>> obj = path[0] # <Country: Russian Federation>

>>> # ID
>>> obj.id
69

>>> # ISO 3166-2
>>> obj.iso_id
u'RU'

>>> # Type
>>> obj.type
u'country'

>>> # Name
>>> obj.name
u'Russian Federation'

>>> # Nesting level
>>> obj.level
0

>>> # Center coordinates
>>> obj.geography.center.latitude
65
>>> obj.geography.center.longitude
55

>>> # Population
>>> obj.population
140000000

>>> # Child object
>>> obj.child
<Region: North West Federal Region>

>>> # Parent object
>>> obj.parent
None
>>> obj.child.parent
<Country: Russian Federation>

Country Properties

>>> # Top-level domain (TLD)
>>> obj.tld
u'ru'

>>> # Official language
>>> lang = obj.language
>>> lang
<Language: Russian>
>>> # Language unique ID ISO 639-1
>>> lang.id
u'ru'
>>> lang.name
u'Russian'

Region Properties

Objects of the GeobazaRegion type have language attribute, the same as objects of the GeobazaCountry type have.

JSON and XML Serialization

Geobaza and GeobazaObject objects can be presented as JSON or XML.

>>> obj = path[0] # <Country: Russian Federation>

>>> # JSON
>>> print obj.to_pretty_json()
{
    "child": "1271",
    "geography": {
        "center": {
            "latitude": 65,
            "longitude": 55
        }
    },
    "id": "69",
    "iso_id": "RU",
    "name": "Russian Federation",
    "population": "140000000",
    "tld": "ru",
    "translations": [
        {
            "en": "Russian Federation",
            "ru": "\u0420\u043e\u0441\u0441\u0438\u0439\u0441\u043a\u0430\u044f \u0424\u0435\u0434\u0435\u0440\u0430\u0446\u0438\u044f",
            "type": "official"
        },
        {
            "en": "Russia",
            "ru": "\u0420\u043e\u0441\u0441\u0438\u044f",
            "type": "alt"
        }
    ],
    "type": "country"
}

>>> # XML
>>> print obj.to_pretty_xml()
<?xml version="1.0" encoding="utf-8"?>
<object child="1271" id="69" type="country">
    <name>
        Russian Federation
    </name>
    <iso-id>
        RU
    </iso-id>
    <geography>
        <center latitude="65" longitude="55"/>
    </geography>
    <population>
        140000000
    </population>
    <translations>
        <group type="official">
            <item language="ru">
                Российская Федерация
            </item>
            <item language="en">
                Russian Federation
            </item>
        </group>
        <group type="alt">
            <item language="ru">
                Россия
            </item>
            <item language="en">
                Russia
            </item>
        </group>
    </translations>
    <language id="ru">
        Russian
    </language>
    <tld>
        ru
    </tld>
</object>

Special Ranges

The special ranges are those that are reserved for special use, and those that are not selected.

For details, see IANA IPv4 Address Space Registry.

>>> # Reserved
>>> obj = query.get('127.0.0.1')

>>> obj
<SpecialRange: Loopback>
>>> obj.type
'special'
>>> obj.name
u'Loopback'

>>> # Unallocated
>>> obj = query.get('170.0.0.0')
<SpecialRange: Unallocated>

>>> path = query.get_path('192.168.0.0')
>>> path
<Geobaza: [<SpecialRange: Private-Use Networks>]>
>>> path.is_apecial
True

geobaza-lookup.py

geobaza-lookup.py is the command line utility, intended for request to Geobaza.

Usage: geobaza-lookup.py [options] ip_address.

$ geobaza-lookup.py 80.250.189.254

 Information for IP-address: 80.250.189.254

 +--<Country: Russian Federation>
 |
 +----<Region: North West Federal Region>
 |
 +------<Region: Novgorod Region>
 |
 +--------<Locality: Velikiy Novgorod>

For more information, see geobaza-lookup.py  -h.