GEOBAZA

Модуль GEOBAZA предназначен для быстрого получения географических данных, таких
как страна, область или штат, город, а также географических координат, по которым
зарегистрирован IP-адрес. Информация предоставляется на трех языках: русском,
английском, а также языке страны, в которой зарегистрирован IP-адрес.

В некоторых случаях точное определение географической привязки IP-адреса
невозможно. Например, пользователь выходит в интернет через GPRS Московского
оператора сотовой связи, находясь при этом в Петербурге.

Модуль Geobaza5 состоит из файлов базы данных: "geobaza.dat", "geobaza.csv",
и нескольких модулей API на языках: PHP, Perl, C. Подробные примеры использования
API можно посмотреть в примерах на вышеуказанных языках программирования.

Файл "geobaza.dat" является бинарным файлом и используется в классе Geobaza.

Файл "geobaza.csv" в текстовом виде предоставляет информацию, хранящуюся в
бинарном файле "geobaza.dat". В классе Geobaza не используется, но может быть
полезен пользователям. Формат записей данного файла:
    *	IP начала диапазона в текстовом виде
    *	IP конца диапазона в текстовом виде
    *	IP начала диапазона в виде 32-битного целого
    *	Размер диапазона (конец-начало+1)
    *	TLD страны
    *	Иерархический идентификатор географического объекта (город, регион, страна)
	Данный идентификатор может меняться от версии к версии! "Жесткая" привязка
	к нему может в последствии вызвать неудобства.
    *	Подробное описание географического объекта в формате JSON.




GEOBAZA Lite

GEOBAZA Lite предоставляет тот же функционал, что и Geobaza, за одним исключением:
точность определения географического объекта ограничивается до региона. Без
ограничений определяются лишь города в Новгородской области.

Для проверки корректности внедрения Geobaza можно проверить один из адресов,
принадлежащих городам в Новгородской области, например, 85.142.15.255.




PHP API

В случае, если PHP собран без встроенной поддержки формата JSON, можно использовать
наши включаемый файл для работы с JSON: include "json-dirty.php". Однако, это является
"грязным" хаком, поэтому рекомендуем пересобрать PHP для встроенной поддержки JSON.

КЛАСС Geobaza

Метод is_valid() - возвращает true, если экземпляр класса Geobaza успешно
загрузил требуемые базы данных и false в противном случае. Если экземпляр не смог
загрузить базы данных, то нижеуказанные методы будут возвращать false.

Метод get_error() - возвращает текстовое значение ошибки, если экземпляр был
создан с ошибкой.

Метод get_headers() - возвращает массив служебных заголовков файла данных:
    'api_version' => 5
    'build_date' => дата и время сборки файла
    'build_timestamp' => дата и время сборки файла, секунды с 1970 года.

Метод lookup($ip4) - возвращает массив.
* В случае, если адрес соответствует специальному диапазону, то
    array('special'=>[ Описание специального диапазона ])
* Если адрес соответствует выделенной сети, то array('items'=>array of items)
    где array of items - упорядоченный массив описаний географического объекта.
    Первый элемент - наиболее детализированное описание объекта (город).
    Последний элемент - обычно страна.
    Каждый элемент является ассоциативным массивом:
    'id' => иерархический идентификатор объекта;
    'type' => тип (world, country, region, city);
    'lang' => государственный язык;
    'lat' => широта;
    'lon' => долгота;
    'population' => численность населения;
    'name' => ассоциативный массив значений 'язык'=>'название'. Для каждого объекта
	поддерживаются название на русском (RU), английском (EN) и национальном языке,
	если он отличен от RU и EN;
    'name_official' => то же, что и 'name', но вместо общеупотребительных названий
	(Россия, Беларусь) используются официальные (Российская Федерация, Республика
	Беларусь).

Все данные, возвращаемые методом, представлены в кодировке UTF-8.




PERL API

Идеологически то же самое, что и PHP API. Различия только в синтаксисе языков.




C API

Все функции возвращают 0 при успешном завершении и не 0 - при неудаче.

int geobaza_open(GEOBAZA *geobaza, char *filename)
    Открывает на чтение бинарный файл и инициализирует структуру данных geobaza.
    Данную структуру можно использовать для неограниченного числа последующих вызовов lookup.

int geobaza_close(GEOBAZA *geobaza)
    Закрывает структуру geobaza.
    
int geobaza_lookup(GEOBAZA *geobaza, u_int32_t ipv4, GEOBAZA_PLACE **ref_to_place)
    Выполняет поиск ip-адреса в формате 32-битного целого по структуре geobaza. Для хранения
    результата передается ссылка на неинициализированный указатель ref_to_place.
    В случае успешного поиска функция сама выделит память под результат.
    
    Указатель ref_to_place будет ссылаться на структуру, описывающую максимально возможный
    распознанный географический объект (город). Если значение поля parent не равно null, то
    оно указывает более высокий объект, следующий в иерархии (регион, страна).
    
int geobaza_free_result(GEOBAZA_PLACE **ref_to_place)
    Освобождает все динамически выделенные под результат области памяти.

int geobaza_aton(char *ipv4_as_text, u_int32_t *ipv4_as_32bit)
    Преобразует ip-адрес из текстового вида aaa.bbb.ccc.ddd в 32-битное беззнаковое целое.