PHP API v1

Installation

Latest Geobaza PHP API version is 1.0.4.

Official releases of Geobaza Lite PHP API are available on the download page: http://geobaza.ru/download/.

Download latest release and unpack it.

curl -OJ http://geobaza.ru/download/latest/php
unzip geobaza-lite-php-api-x.x.zip

Distribution contents:

geobaza/data/geobaza.dat
geobaza/example.php
geobaza/geobaza-lookup.php
geobaza/geobaza.php
geobaza/tests.php
geobaza/utils.php
ChangeLog
LICENSE
README
MANIFEST

System Requirements

  • PHP 5+

Tip

Outdated API for PHP4 is available in main Geobaza distribution and located in php4 directory.

Dependencies

  • JSON support
  • libxml
  • iconv or mbstring extensions (for character encodings conversion operations)
  • PHPUnit for running tests

Usage

Getting Started

# Import Geobaza
require_once 'geobaza/geobaza.php';

$ip = '85.142.15.254';

/**
* Initialize
*/

$query = new GeobazaQuery();

/**
* Headers: API version, binary file release version, build time
*/

$query->headers->release;
# '11.10'
$query->headers->build_date;
# Fri Sep 30 18:15:36 MSK 2011
$query->headers->api_version;
# 5
$query->headers->build_timestamp;
# 1317392136

Character Encodings Conversion

New in version 1.0.2

If you need results in encoding other than UTF-8 (by default), you must specify encoding in GeobazaQuery constructor.

Supported encodings:

// Set character encoding
$query = new GeobazaQuery(FILE_PATH, NO_CACHE, 'cp1251');

Now, all data will be encoded in cp1251. This also applies to the Geobaza->to_xml() and GeobazaObject->to_xml() methods.

Note

Geobaza->to_json() and GeobazaObject->to_json() methods always returns UTF-8 encoded strings.

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.

/**
* Get single object
*/

$obj = $query->get($ip);

/**
* Object properties
*/

# Name
$obj->name;
# Velikiy Novgorod

# Type
$obj->type;
# locality

# Unique ID
$obj->id;
# 5069

# Nesting level
$obj->level;
# 3

# Coordinates
$obj->geography->center->latitude;
# 58.516
$obj->geography->center->longitude;
# 31.283

# Parent object
$obj->parent->name;
# 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.

/**
* Get full path
*/

$geobaza = $query->get_path($ip);

# Iteration over objects list
foreach ($geobaza as $obj) {
    $obj->name;
}
# Russian Federation
# North West Federal Region
# Novgorod Region
# Velikiy Novgorod

# You can also access to Geobaza items via indexes, like in array
for ($i = 0; $i < count($geobaza); $i++) {
    $geobaza[$i]->name;
}
# Result will be the same

# Geobaza object is countable
# Standard count() function works with it
count($geobaza);
# 4

# Country
$geobaza->country->name;
# Russian Federation

# Regions
foreach ($geobaza->regions as $obj) {
    $obj->name;
}
# North West Federal Region
# Novgorod Region

# Localities
foreach ($geobaza->localities as $obj) {
    $obj->name;
}
# Velikiy Novgorod

Objects Properties

Common

$obj = $geobaza->first(); # Russian Federation
# This syntax is equal access by index
$obj = $geobaza[0]; # Russian Federation

# ID
$obj->id;
# 69

# ISO 3166-2
$obj->iso_id;
# 'RU'

# Type
$obj->type;
# 'country'

# Name
$obj->name;
# '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->name;
# North West Federal Region

# Parent object
$obj->parent;
# NULL
$obj->child->parent->name;
# Russian Federation

Translations

Translations stored in translations attribute, ordered by priority. You can access them by index, that equals priority value.

$obj->translations[0]->ru;
# Российская Федерация
$obj->translations[0]->en;
# Russian Federation
$obj->translations[0]->type;
# official

Country Properties

# Top-level domain (TLD)
$obj->tld;
# 'ru'

# Official language
$lang = $obj->language;
# Language unique ID ISO 639-1
$lang->id;
# 'ru'
$lang->name;
# '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.

Note

Geobaza->to_pretty_json() works only with PHP >= 5.4. For lower PHP versions use to_json() method.

$obj = $geobaza[0]; # Russian Federation

>>> # JSON
>>> echo $obj->to_pretty_json(), PHP_EOL;
{ "child" : 1271,
"geography" : { "center" : { "latitude" : 65,
        "longitude" : 55
        } },
"id" : 69,
"iso_id" : "RU",
"language" : { "id" : "ru",
    "name" : "Russian"
    },
"level" : 0,
"name" : "Russian Federation",
"population" : 140000000,
"tld" : "ru",
"translations" : [ { "en" : "Russian Federation",
        "ru" : "Российская Федерация",
        "type" : "official"
    },
    { "en" : "Russia",
        "ru" : "Россия",
        "type" : "alt"
    }
    ],
"type" : "country"
}

>>> # XML
>>> echo $obj->to_pretty_xml(), PHP_EOL;
<?xml version="1.0" encoding="utf-8"?>
<object type="country" id="69" level="0" child="1271">
  <name>Russian Federation</name>
  <iso-id>RU</iso-id>
  <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>
  <geography>
    <center latitude="65" longitude="55"/>
  </geography>
  <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.

/**
* Special Ranges
*/

# Reserved
$obj = $query->get('127.0.0.1');

$obj instanceof SpecialRange;
# true
$obj->type;
# special
$obj->name;
# Loopback

# Unallocated
$obj = $query->get('170.0.0.0');
$obj->name;
# Unallocated

/**
* Geobaza object 'is_special' flag
*/

$path = $query->get_path('192.168.0.0');

$path->is_special;
# true

geobaza-lookup.php

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

Usage: geobaza-lookup.php ip_address.

$ geobaza-lookup.php 80.250.189.254

 Information for IP-address: 80.250.189.254

 +--Russian Federation
 |
 +----North West Federal Region
 |
 +------Novgorod Region
 |
 +--------Velikiy Novgorod