sanmai/pindx

Эталонный справочник почтовых индексов объектов почтовой связи


README

Latest Stable Version Build Status JSON API

Справочник почтовых индексов

Установка делается как обычно.

composer require sanmai/pindx

Для использования предлагаются три интерфейса.

  • С помощью первого можно получить данные конкретного отделения в офлайн режиме, из локальной копии БД.
  • Второй интерфейс подразумевает получение данных отделения по JSON API почтовых индексов. Это можно сделать только через запрос к API, потому этот метод работает более медленно, чем первый. С другой стороны, использование этого метода исключает необходимость время от времени обновлять версию пакета для обновления базы индексов.
  • Третий предназначен для пакетной проверки большого числа индексов, по локальной копии БД.

Источник данных этой библиотеки: эталонный справочник почтовых индексов объектов почтовой связи от дирекции технологий и информатизации ФГУП «Почта России».

Получение данных отделения из локальной копии БД

$office = \RussianPostIndex\PrefixDirectory::getOffice($postalCode);

Возвращает или объект имплементирующий интерфейс Record, или, если такого отделения нет, null. Нет необходимости как-то отдельно проверять корректность индекса. Если индекса в БД нет, то вернётся null.

Интерфейс объекта содержит следующие методы для получения данных об отделении:

/**
 * Почтовый индекс объекта почтовой связи в соответствии с действующей системой индексации.
 */
$office->getIndex();

/**
 * Наименование объекта почтовой связи.
 */
$office->getName();

/**
 * Тип объекта почтовой связи.
 */
$office->getType();

/**
 * Индекс вышестоящего по иерархии подчиненности объекта почтовой связи.
 */
$office->getSuperior();

/**
 * Наименование области, края, республики, в которой находится объект почтовой связи.
 */
$office->getRegion();

/**
 * Наименование автономной области, в которой находится объект почтовой связи.
 */
$office->getAutonomousRegion();

/**
 * Наименование района, в котором находится объект почтовой связи.
 */
$office->getArea();

/**
 * Наименование населенного пункта, в котором находится объект почтовой связи.
 */
$office->getCity();

/**
 * Наименование подчиненного населенного пункта, в котором находится объект почтовой связи.
 */
$office->getDistrict();

/**
 * Дата актуализации информации об объекте почтовой связи. 
 * @return DateTimeInterface
 */
$office->getDate();

Пример использования

<?php
require 'vendor/autoload.php';

$postalCode = 130980;
if ($office = \RussianPostIndex\PrefixDirectory::getOffice($postalCode)) {
    var_dump($office->getIndex()); // int(130980)
    var_dump($office->getName()); // string(25) "Москва EMS ММПО"
    var_dump($office->getType()); // string(8) "ММПО"
    var_dump($office->getSuperior()); // int(104040)
    var_dump($office->getRegion()); // string(12) "Москва"
    var_dump($office->getAutonomousRegion()); // string(0) ""
    var_dump($office->getArea()); // string(0) ""
    var_dump($office->getCity()); // string(0) ""
    var_dump($office->getDistrict()); // string(0) ""
    var_dump($office->getDate()->format('Y-m-d')); // string(10) "2017-04-28"
}

Получение данных отделения используя JSON API

$client = new \RussianPostIndex\Client();
$office = $client->getOffice(101000);

Возвращает или объект имплементирующий интерфейс Record, или, если такого отделения нет, null. Нет необходимости как-то отдельно проверять корректность индекса. Если индекса в БД нет, то вернётся null.

Конструктор класса \RussianPostIndex\Client опционально берёт на вход стандартный интерфейс клиента Guzzle, что позволяет добавить подключение через прокси или поменять используемый сервер, поднять таймауты для соединения.

Пример использования

<?php
require 'vendor/autoload.php';

$postalCode = 130980;

$client = new \RussianPostIndex\Client();
if ($office = $client->getOffice($postalCode)) {
    var_dump($office->getIndex()); // int(130980)
    var_dump($office->getName()); // string(25) "Москва EMS ММПО"
    var_dump($office->getType()); // string(8) "ММПО"
    var_dump($office->getSuperior()); // int(104040)
    var_dump($office->getRegion()); // string(12) "Москва"
    var_dump($office->getAutonomousRegion()); // string(0) ""
    var_dump($office->getArea()); // string(0) ""
    var_dump($office->getCity()); // string(0) ""
    var_dump($office->getDistrict()); // string(0) ""
    var_dump($office->getDate()->format('Y-m-d')); // string(10) "2017-04-28"
}

Проверка индекса

Метод для проверки индексов загружает весь список индексов в память, потому проверка индексов происходит быстрее, без обращения к файловой системе. Соответственно, первичная загрузка БД занимает ощутимое время и этот метод не имеет смысла использовать для проверки одного-двух-трёх индексов.

$postalCode = 130980;
$postalCodeValid = \RussianPostIndex\MainDirectory::postalCodeValid($postalCode);
var_dump($postalCodeValid);
// bool(true)

Существуют способы ещё более ускорить работу алгоритма проверки индексов, с большим использованием памяти и существенно более медленной инициализацией поискового индекса. В этой библиотеке такие методы пока не имплементированы.

JSON

Для вашего удобства все данные из БД также есть в виде JSON API почтовых индексов.

API - бесплатное, обратная ссылка - желательна. Сами файлы.

Обновление и разработка

Обновление справочника производится в автоматическом режиме вызовом make, последующим коммитом и PR.

Что за pindx?

Потому что так называются исходные файлы от почты. Конечно, они называются используя смешанный регистр, PIndx, но в именах пакетов в Composer не рекомендуется использовать такой формат. Потому pindx.