PHP API SDK - "КЛАДР в облаке"

PHP API для интеграции с сервисом "ФИАС в облаке". Данный SDK поможет быстрее внедрить в ваш проект инструменты взаимодействия с актуальной база всех почтовых адресов России.

---

ФИАС в облаке — актуальная база всех почтовых адресов России. Легко интегрируется с вашим сайтом, помогает устранить ошибки при написании адресов и делает этот процесс быстрым и удобным.

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

---

Перед началом работы

• Требуется PHP 8.0 или выше.
• Требуется наличие реализации PSR-18 (HTTP Client).

В SDK применяется спецификация PSR-18 (HTTP-client). Это значит, что в вашем проекте должны быть зарегистрированы классы, реализующие эту спецификацию (например, Guzzle).

Для автоматического обнаружения зависимостей используются пакеты psr-discovery. Подробнее, об автоматическом обнаружении зависимостей

---

Установка

Установка осуществляется с помощью пакетного менеджера Composer

composer require webmasterskaya/php-kladr-api

---

Инициализация

Для начала работы, создайте экземпляр клиента:

$client = new \Webmasterskaya\Kladr\Client(string $token, array $config => []);

Список параметров:

• token - токен доступа. Опционально. Получить токен доступа, можно здесь. При использовании клиента без токена, подключение будет осуществляться по бесплатному тарифу.
• config - массив с параметрами клиента. Опциональное. По-умолчанию - пустой массив. Допустимые поля:
  • url - определяет, по какому адресу библиотека будет пытаться подключиться к API

---

Поиск по всем доступным полям адреса

Для выполнения полнотекстового поиска по всем доступным полям адреса, обратитесь к методу queryString:

$result = $client->queryString(string $query, array $config = [], int $limit = 10, int $offset = 0);

Метод вернёт массив со списком объектов, содержащих поисковую фразу. Подробнее смотрите в разделе "Ответ сервиса"

Note Если в $query передать слово "Новгород", то в ответе будут возвращены адреса у которых это слово встречается в названии Региона, Населённого пункта и Улицы

Список параметров:

• query - строка запроса (что хотите найти?)
• config - массив с параметрами запроса. Опциональное. По-умолчанию - пустой массив. Допустимые поля:
  • withParent - если установить этот параметр равным 1 или true, то в ответ будут включены родительские объекты (для района это регион, для населённого пункта - район и регион и т.п.)
  • regionId, districtId, cityId - идентификатор региона, района и населённого пункта, соответственно. Применяется для ограничения поиска внутри конкретного объекта.
• limit - количество результатов в ответе. Опциональное. По-умолчанию - 10. Чтобы вернуть весь список, без ограничения, установите limit равным нулю
• offset - смещение результатов (для организации постраничной навигации). Опциональное. По-умолчанию - 0

---

Поиск только по указанному полю адреса

Для выполнения поиска только по указанному полю адреса (например, только в названиях городов), обратитесь к методу queryField:

$result = $client->queryString(string $query, array $config = [], int $limit = 10, int $offset = 0);

Метод вернёт массив со списком объектов, содержащих поисковую фразу, в указанном поле. Подробнее смотрите в разделе "Ответ сервиса"

Список параметров:

• query - строка запроса (что хотите найти?)
• config - массив с параметрами запроса. Обязательное. Допустимые поля:
  • withParent - если установить этот параметр равным 1 или true, то в ответ будут включены родительские объекты (для района это регион, для населённого пункта - район и регион и т.п.)
  • regionId, districtId, cityId, streetId, buildingId - идентификатор региона, района, населённого пункта, улицы и строения, соответственно. Применяется для ограничения поиска внутри конкретного объекта.
  • contentType - тип объекта (поле), по которому производится поиск. Обязательное. Допустимые типы объектов
    • zip - почтовый индекс. Работает только при contentType = building.
  • typeCode - тип населённого пункта. Указывает, какие типы населённых пунктов будут участвовать в поиске. Допустимые типы населённых пунктов. Поддерживается битовая комбинация (например, для получения списка только сёл и деревень, передайте Code::VILLAGE | Code::RURAL)
• limit - количество результатов в ответе. Опциональное. По-умолчанию - 10. Чтобы вернуть весь список, без ограничения, установите limit равным нулю
• offset - смещение результатов (для организации постраничной навигации). Опциональное. По-умолчанию - 0

---

Допустимые типы объектов

Все доступные типы перечисленны в класе Webmasterskaya\Kladr\Type\Content

Константа	Значение	Описание
Content:REGION	'region'	Осуществлять поиск только по полю "Название региона"
Content:DISTRICT	'district'	Осуществлять поиск только по полю "Название район"
Content:CITY	'city'	Осуществлять поиск только по полю "Название населённого пункта"
Content:STREET	'street'	Осуществлять поиск только по полю "Название улицы"
Content:BUILDING	'building'	Осуществлять поиск только по полю "Номер дома"

Допустимые типы населённых пунктов

Все доступные типы перечисленны в класе Webmasterskaya\Kladr\Type\Code

Константа	Значение	Описание
Code::CITY	1	В ответ будут включены населённые пункты с типом "Город"
Code::VILLAGE	2	В ответ будут включены населённые пункты с типом "Село"
Code::RURAL	4	В ответ будут включены населённые пункты с типом "Деревня"

---

Ответ сервиса

Пример ответа, без родительских объектов

[
    "searchContext" => // Массив с параметрами запроса
        [
            "oneString" => "1",
            "query" => "Новгород"
        ],
    "result" => [ // Результаты поиска
        [
            "id" => "5200000100000", // КЛАДР Код объекта
            "name" => "Нижний Новгород", // Название объекта
            "zip" => null, // Почтовый индекс
            "type" => "Город", // Тип объекта
            "typeShort" => "г", // Короткая запись типа объекта
            "okato" => "22401000000", // Код ОКАТО 
            "contentType" => "city", // Тип объекта, в соответсвии с типами объектов, описанными в классе \Webmasterskaya\Kladr\Type\Content
            "fullName" => "Нижегородская Область, Город Нижний Новгород", // Полный адрес объекта
            "guid" => "555e7d61-d9a7-4ba6-9770-6caa8198c483", // ФИАС Код объекта
            "ifnsfl" => "", // Код ФНС для физических лиц
            "ifnsul" => "", // Код ФНС для юридических лиц
            "oktmo" => "22701000001", // Код ОКТМО
            "parentGuid" => "88cd27e2-6a8a-4421-9718-719a28a0a088", // ФИАС Код родительского объекта
            "cadnum" => "" // ???
        ]
    ]
];

Пример ответа, с перечнем родительских объектов

[
  "searchContext"=> [ // Массив с параметрами запроса
    "contentType"=> "city",
    "query"=> "Новом",
    "withParent"=> "1",
    "limit"=> 1
  ],
  "result"=> [ // Результаты поиска
    [
      "id"=> "6201200200000", // КЛАДР Код объекта
      "name"=> "Новомичуринск", // Название объекта
      "zip"=> 391160, // Почтовый индекс
      "type"=> "Город", // Тип объекта
      "typeShort"=> "г", // Короткая запись типа объекта
      "okato"=> "61225514000", // Код ОКАТО 
      "contentType"=> "city", // Тип объекта, в соответсвии с типами объектов, описанными в классе \Webmasterskaya\Kladr\Type\Content
      "guid"=> "dc0c31cd-e03e-4fc3-a714-1c9f4b61cc7e",  // Полный адрес объекта
      "ifnsfl"=> "6219", // Код ФНС для физических лиц
      "ifnsul"=> "6219", // Код ФНС для юридических лиц
      "oktmo"=> "61625114001", // Код ОКТМО
      "parentGuid"=> "0b2f6225-49e6-49d0-ab5b-625b9fb94554", // ФИАС Код родительского объекта
      "cadnum"=> "", // ???
      "parents"=> [ // Массив родительских объектов, отсортированный от более крупного, к более мелкому (Регион->Район->Нас.пункт->Улица)
        [
          "id"=> "6200000000000",
          "name"=> "Рязанская",
          "zip"=> 390000,
          "type"=> "Область",
          "typeShort"=> "обл",
          "okato"=> "61000000000",
          "contentType"=> "region",
          "guid"=> "963073ee-4dfc-48bd-9a70-d2dfc6bd1f31",
          "ifnsfl"=> "6200",
          "ifnsul"=> "6200",
          "oktmo"=> "61000000",
          "parentGuid"=> "",
          "cadnum"=> ""
        ],
        [
          "id"=> "6201200000000",
          "name"=> "Пронский",
          "zip"=> 391159,
          "type"=> "Район",
          "typeShort"=> "р-н",
          "okato"=> "61225000000",
          "contentType"=> "district",
          "guid"=> "0b2f6225-49e6-49d0-ab5b-625b9fb94554",
          "ifnsfl"=> "6219",
          "ifnsul"=> "6219",
          "oktmo"=> "",
          "parentGuid"=> "963073ee-4dfc-48bd-9a70-d2dfc6bd1f31",
          "cadnum"=> ""
        ]
      ]
    ]
  ]
]

---

Автоматическое обнаружение зависимостей

Ознакомиться со списком автоматически обнаруживаемых библиотек можно по ссылкам ниже:

• PSR-18 (HTTP Client)

Если в списке автоматического обнаружения нет библиотеки, используемой на вашем проекте, то её нужно зарегистрировать самостоятельно. Подробнее, о ручной регистрации зависимостей

---

Ручная регистрация зависимостей

Пример регистрации HttpClient в Bitrix

\PsrDiscovery\Implementations\Psr18\Clients::add(
    \PsrDiscovery\Entities\CandidateEntity::create(
        'bitrix/main',
        '~23',
        static function (string $class = '\Bitrix\Main\Web\HttpClient') {
            return new $class;
        }
    )
);

Пример регистрации HttpClient в Joomla

\PsrDiscovery\Implementations\Psr18\Clients::add(
    \PsrDiscovery\Entities\CandidateEntity::create(
        'joomla/http',
        '~3',
        static function (string $class = '\Joomla\Http\Http') {
            return new $class;
        }
    )
);