RESTful web API v1

Overview

You can get access to Geobaza IP-address geolocation service via RESTful web API.

API is available at http://geobaza.ru/api/1/.

API Access

To get access to API, you should get the key at http://geobaza.ru/profile/key/. To get access to this page, authorize at the website using OpenID.

Limitations

The free version allows sending 100 requests within 24 hours using one key. You can change the key only one time withing 24 hours. The requests statistics is cleared at 00:00 UTC.

The requests statistics is available in real-time at: http://geobaza.ru/profile/key/#stats.

Resources

IP

Resource URI: http://geobaza.ru/api/1/ip/v4/{x.x.x.x}/. Where {x.x.x.x} — any valid IPv4 address.

Available methods: GET.

Parameters

Parameters List
ParameterRequiredDescriptionValues
keyYesAPI key 
formatNoResponse format
  • xml
  • json

Default: json

resultNoResponse type: specific geographical object or full path
  • object
  • path

Default: object

prettyNoResponse formatting for comprehensive view displayed for the user
  • 0
  • 1

Default: 0

Response Format

API response is moved to response container.

Response Fields Description
FieldTypeRequiredDescriptionValues
codeIntegerYesHTTP response code
200, in case
of no errors
statusStringYesResponse status In case of error, its description will be here
OK, in case
of no errors
JSON

API request about specific geographical object.

http://geobaza.ru/api/1/ip/v4/85.142.15.254/?key=<your-api-key>

API response.

{
    "response": {
        "code": 200,
        "geobaza": {
            "api_version": 5,
            "build_date": "2011-09-20T15:52:07",
            "build_timestamp": 1316519527,
            "ip": "85.142.15.254",
            "is_lite": "0",
            "is_special": "0",
            "objects": [
                {
                    "geography": {
                        "center": {
                            "latitude": 58.515999999999998,
                            "longitude": 31.283000000000001
                        }
                    },
                    "id": "5069",
                    "iso_id": "",
                    "name": "Velikiy Novgorod",
                    "parent": "4710",
                    "population": "216200",
                    "translations": [
                        {
                            "en": "Velikiy Novgorod",
                            "ru": "\u0412\u0435\u043b\u0438\u043a\u0438\u0439 \u041d\u043e\u0432\u0433\u043e\u0440\u043e\u0434",
                            "type": "official"
                        },
                        {
                            "en": "Velikiy Novgorod",
                            "type": "alt"
                        }
                    ],
                    "type": "locality"
                }
            ],
            "query_timestamp": "1316613514.13",
            "release": "5.0.8"
        },
        "status": "OK"
    }
}

API request about full path to the geographical object. In this case, the objects storage contains full hierarchical list of objects instead of one.

http://geobaza.ru/api/1/ip/v4/85.142.15.254/?key=<your-api-key>&result=path

API response.

{
    "response": {
        "code": 200,
        "geobaza": {
            "api_version": 5,
            "build_date": "2011-09-20T15:52:07",
            "build_timestamp": 1316519527,
            "ip": "85.142.15.254",
            "is_lite": "0",
            "is_special": "0",
            "objects": [
                {
                    "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"
                },
                {
                    "child": "4710",
                    "geography": {
                        "center": {
                            "latitude": 61.216000000000001,
                            "longitude": 36.381999999999998
                        }
                    },
                    "id": "1271",
                    "iso_id": "",
                    "language": {
                        "id": "ru",
                        "name": "Russian"
                    },
                    "name": "North West Federal Region",
                    "parent": "69",
                    "population": "13462259",
                    "translations": [
                        {
                            "en": "North West Federal Region",
                            "ru": "\u0421\u0435\u0432\u0435\u0440\u043e-\u0417\u0430\u043f\u0430\u0434\u043d\u044b\u0439 \u0444\u0435\u0434\u0435\u0440\u0430\u043b\u044c\u043d\u044b\u0439 \u043e\u043a\u0440\u0443\u0433",
                            "type": "official"
                        },
                        {
                            "en": "North-West Federal Region",
                            "ru": "\u0421\u0435\u0432\u0435\u0440\u043e-\u0417\u0430\u043f\u0430\u0434\u043d\u044b\u0439 \u0444\u0435\u0434\u0435\u0440\u0430\u043b\u044c\u043d\u044b\u0439 \u043e\u043a\u0440\u0443\u0433",
                            "type": "alt"
                        }
                    ],
                    "type": "region"
                },
                {
                    "child": "5069",
                    "geography": {
                        "center": {
                            "latitude": 58.441000000000003,
                            "longitude": 32.012
                        }
                    },
                    "id": "4710",
                    "iso_id": "",
                    "language": {
                        "id": "ru",
                        "name": "Russian"
                    },
                    "name": "Novgorod Region",
                    "parent": "1271",
                    "population": "652400",
                    "translations": [
                        {
                            "en": "Novgorod Region",
                            "ru": "\u041d\u043e\u0432\u0433\u043e\u0440\u043e\u0434\u0441\u043a\u0430\u044f \u043e\u0431\u043b\u0430\u0441\u0442\u044c",
                            "type": "official"
                        },
                        {
                            "en": "Novgorod Region",
                            "ru": "\u041d\u043e\u0432\u0433\u043e\u0440\u043e\u0434\u0441\u043a\u0430\u044f \u043e\u0431\u043b\u0430\u0441\u0442\u044c",
                            "type": "alt"
                        }
                    ],
                    "type": "region"
                },
                {
                    "geography": {
                        "center": {
                            "latitude": 58.515999999999998,
                            "longitude": 31.283000000000001
                        }
                    },
                    "id": "5069",
                    "iso_id": "",
                    "name": "Velikiy Novgorod",
                    "parent": "4710",
                    "population": "216200",
                    "translations": [
                        {
                            "en": "Velikiy Novgorod",
                            "ru": "\u0412\u0435\u043b\u0438\u043a\u0438\u0439 \u041d\u043e\u0432\u0433\u043e\u0440\u043e\u0434",
                            "type": "official"
                        },
                        {
                            "en": "Velikiy Novgorod",
                            "type": "alt"
                        }
                    ],
                    "type": "locality"
                }
            ],
            "query_timestamp": "1316613789.23",
            "release": "5.0.8"
        },
        "status": "OK"
    }
}
XML

API request about specific geographical object.

http://geobaza.ru/api/1/ip/v4/85.142.15.254/?key=<your-api-key>&format=xml

API response.

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>
        OK
    </status>
    <code>
        200
    </code>
    <geobaza api-version="5" build-date="2011-09-20T15:52:07" build-timestamp="1316519527" ip="85.142.15.254" is-lite="0" is-special="0" query-timestamp="1316614068.17" release="5.0.8">
        <objects>
            <object id="5069" parent="4710" type="locality">
                <name>
                    Velikiy Novgorod
                </name>
                <iso-id/>
                <geography>
                    <center latitude="58.516" longitude="31.283"/>
                </geography>
                <population>
                    216200
                </population>
                <translations>
                    <group type="official">
                        <item language="ru">
                            Великий Новгород
                        </item>
                        <item language="en">
                            Velikiy Novgorod
                        </item>
                    </group>
                    <group type="alt">
                        <item language="en">
                            Velikiy Novgorod
                        </item>
                    </group>
                </translations>
            </object>
        </objects>
    </geobaza>
</response>

API request about full path to geographical object. In this case, the objects tag contains full hierarchical list of objects instead of one.

http://geobaza.ru/api/1/ip/v4/85.142.15.254/?key=<your-api-key>&format=xml&result=path

API response.

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>
        OK
    </status>
    <code>
        200
    </code>
    <geobaza api-version="5" build-date="2011-09-20T15:52:07" build-timestamp="1316519527" ip="85.142.15.254" is-lite="0" is-special="0" query-timestamp="1316614114.56" release="5.0.8">
        <objects>
            <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>
            <object child="4710" id="1271" parent="69" type="region">
                <name>
                    North West Federal Region
                </name>
                <iso-id/>
                <geography>
                    <center latitude="61.216" longitude="36.382"/>
                </geography>
                <population>
                    13462259
                </population>
                <translations>
                    <group type="official">
                        <item language="ru">
                            Северо-Западный федеральный округ
                        </item>
                        <item language="en">
                            North West Federal Region
                        </item>
                    </group>
                    <group type="alt">
                        <item language="ru">
                            Северо-Западный федеральный округ
                        </item>
                        <item language="en">
                            North-West Federal Region
                        </item>
                    </group>
                </translations>
                <language id="ru">
                    Russian
                </language>
            </object>
            <object child="5069" id="4710" parent="1271" type="region">
                <name>
                    Novgorod Region
                </name>
                <iso-id/>
                <geography>
                    <center latitude="58.441" longitude="32.012"/>
                </geography>
                <population>
                    652400
                </population>
                <translations>
                    <group type="official">
                        <item language="ru">
                            Новгородская область
                        </item>
                        <item language="en">
                            Novgorod Region
                        </item>
                    </group>
                    <group type="alt">
                        <item language="ru">
                            Новгородская область
                        </item>
                        <item language="en">
                            Novgorod Region
                        </item>
                    </group>
                </translations>
                <language id="ru">
                    Russian
                </language>
            </object>
            <object id="5069" parent="4710" type="locality">
                <name>
                    Velikiy Novgorod
                </name>
                <iso-id/>
                <geography>
                    <center latitude="58.516" longitude="31.283"/>
                </geography>
                <population>
                    216200
                </population>
                <translations>
                    <group type="official">
                        <item language="ru">
                            Великий Новгород
                        </item>
                        <item language="en">
                            Velikiy Novgorod
                        </item>
                    </group>
                    <group type="alt">
                        <item language="en">
                            Velikiy Novgorod
                        </item>
                    </group>
                </translations>
            </object>
        </objects>
    </geobaza>
</response>