PHPackages webmasterskaya/php-kladr-api - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. webmasterskaya/php-kladr-api AbandonedArchivedLibrary webmasterskaya/php-kladr-api ============================ 12PHP Since Feb 12Pushed 2y ago1 watchersCompare [ Source](https://github.com/webmasterskaya/php-kladr-api)[ Packagist](https://packagist.org/packages/webmasterskaya/php-kladr-api)[ RSS](/packages/webmasterskaya-php-kladr-api/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependenciesVersions (1)Used By (0) PHP API SDK - "КЛАДР в облаке" ============================== [](#php-api-sdk---кладр-в-облаке) PHP API для [интеграции с сервисом "ФИАС в облаке"](https://kladr-api.ru/). Данный SDK поможет быстрее внедрить в ваш проект инструменты взаимодействия с актуальной база всех почтовых адресов России. --- ФИАС в облаке — актуальная база всех почтовых адресов России. Легко интегрируется с вашим сайтом, помогает устранить ошибки при написании адресов и делает этот процесс быстрым и удобным. Подходит для интернет-магазинов, почтовых и курьерских служб, микрофинансирования и сайтов, где клиенту требуется указать адрес. --- ### Перед началом работы [](#перед-началом-работы) - Требуется PHP 8.0 или выше. - Требуется наличие реализации [PSR-18 (HTTP Client)](https://www.php-fig.org/psr/psr-18/). В SDK применяется спецификация [PSR-18 (HTTP-client)](https://www.php-fig.org/psr/psr-18/). Это значит, что в вашем проекте должны быть зарегистрированы классы, реализующие эту спецификацию (например, [Guzzle](https://github.com/guzzle/guzzle)). Для автоматического обнаружения зависимостей используются пакеты [psr-discovery](https://github.com/psr-discovery). Подробнее, об [автоматическом обнаружении зависимостей](#%D0%B0%D0%B2%D1%82%D0%BE%D0%BC%D0%B0%D1%82%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%BE%D0%B5-%D0%BE%D0%B1%D0%BD%D0%B0%D1%80%D1%83%D0%B6%D0%B5%D0%BD%D0%B8%D0%B5-%D0%B7%D0%B0%D0%B2%D0%B8%D1%81%D0%B8%D0%BC%D0%BE%D1%81%D1%82%D0%B5%D0%B9) --- ### Установка [](#установка) Установка осуществляется с помощью пакетного менеджера Composer ``` composer require webmasterskaya/php-kladr-api ``` --- ### Инициализация [](#инициализация) Для начала работы, создайте экземпляр клиента: ``` $client = new \Webmasterskaya\Kladr\Client(string $token, array $config => []); ``` **Список параметров:** - `token` - токен доступа. Опционально. Получить токен доступа, можно [здесь](https://kladr-api.ru/prices). *При использовании клиента без токена, подключение будет осуществляться по бесплатному тарифу.* - `config` - массив с параметрами клиента. Опциональное. По-умолчанию - пустой массив. Допустимые поля: - `url` - определяет, по какому адресу библиотека будет пытаться подключиться к API --- ### Поиск по всем доступным полям адреса [](#поиск-по-всем-доступным-полям-адреса) Для выполнения полнотекстового поиска по всем доступным полям адреса, обратитесь к методу `queryString`: ``` $result = $client->queryString(string $query, array $config = [], int $limit = 10, int $offset = 0); ``` Метод вернёт массив со списком объектов, содержащих поисковую фразу. Подробнее смотрите в разделе "[Ответ сервиса](#%D0%BE%D1%82%D0%B2%D0%B5%D1%82-%D1%81%D0%B5%D1%80%D0%B2%D0%B8%D1%81%D0%B0)" > **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); ``` Метод вернёт массив со списком объектов, содержащих поисковую фразу, в указанном поле. Подробнее смотрите в разделе "[Ответ сервиса](#%D0%BE%D1%82%D0%B2%D0%B5%D1%82-%D1%81%D0%B5%D1%80%D0%B2%D0%B8%D1%81%D0%B0)" **Список параметров:** - `query` - строка запроса (что хотите найти?) - `config` - массив с параметрами запроса. Обязательное. Допустимые поля: - `withParent` - если установить этот параметр равным 1 или `true`, то в ответ будут включены родительские объекты (для района это регион, для населённого пункта - район и регион и т.п.) - `regionId`, `districtId`, `cityId`, `streetId`, `buildingId` - идентификатор региона, района, населённого пункта, улицы и строения, соответственно. Применяется для ограничения поиска внутри конкретного объекта. - `contentType` - тип объекта (поле), по которому производится поиск. **Обязательное**. [Допустимые типы объектов](#%D0%B4%D0%BE%D0%BF%D1%83%D1%81%D1%82%D0%B8%D0%BC%D1%8B%D0%B5-%D1%82%D0%B8%D0%BF%D1%8B-%D0%BE%D0%B1%D1%8A%D0%B5%D0%BA%D1%82%D0%BE%D0%B2) - `zip` - почтовый индекс. Работает только при contentType = building. - `typeCode` - тип населённого пункта. Указывает, какие типы населённых пунктов будут участвовать в поиске. [Допустимые типы населённых пунктов](#%D0%B4%D0%BE%D0%BF%D1%83%D1%81%D1%82%D0%B8%D0%BC%D1%8B%D0%B5-%D1%82%D0%B8%D0%BF%D1%8B-%D0%BD%D0%B0%D1%81%D0%B5%D0%BB%D1%91%D0%BD%D0%BD%D1%8B%D1%85-%D0%BF%D1%83%D0%BD%D0%BA%D1%82%D0%BE%D0%B2). Поддерживается битовая комбинация (например, для получения списка только сёл и деревень, передайте `Code::VILLAGE | Code::RURAL`) - `limit` - количество результатов в ответе. Опциональное. По-умолчанию - 10. Чтобы вернуть весь список, без ограничения, установите `limit` равным нулю - `offset` - смещение результатов (для организации постраничной навигации). Опциональное. По-умолчанию - 0 --- ### Допустимые типы объектов [](#допустимые-типы-объектов) Все доступные типы перечисленны в класе [`Webmasterskaya\Kladr\Type\Content`](src/Type/Content.php) КонстантаЗначениеОписание`Content:REGION`***'region'***Осуществлять поиск только по полю "Название региона"`Content:DISTRICT`***'district'***Осуществлять поиск только по полю "Название район"`Content:CITY`***'city'***Осуществлять поиск только по полю "Название населённого пункта"`Content:STREET`***'street'***Осуществлять поиск только по полю "Название улицы"`Content:BUILDING`***'building'***Осуществлять поиск только по полю "Номер дома"### Допустимые типы населённых пунктов [](#допустимые-типы-населённых-пунктов) Все доступные типы перечисленны в класе [`Webmasterskaya\Kladr\Type\Code`](src/Type/Code.php) КонстантаЗначениеОписание`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)](https://github.com/psr-discovery/http-client-implementations?tab=readme-ov-file#implementations) Если в списке автоматического обнаружения нет библиотеки, используемой на вашем проекте, то её нужно зарегистрировать самостоятельно. Подробнее, о [ручной регистрации зависимостей](#%D1%80%D1%83%D1%87%D0%BD%D0%B0%D1%8F-%D1%80%D0%B5%D0%B3%D0%B8%D1%81%D1%82%D1%80%D0%B0%D1%86%D0%B8%D1%8F-%D0%B7%D0%B0%D0%B2%D0%B8%D1%81%D0%B8%D0%BC%D0%BE%D1%81%D1%82%D0%B5%D0%B9) --- ### Ручная регистрация зависимостей [](#ручная-регистрация-зависимостей) #### Пример регистрации HttpClient в Bitrix [](#пример-регистрации-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 [](#пример-регистрации-httpclient-в-joomla) ``` \PsrDiscovery\Implementations\Psr18\Clients::add( \PsrDiscovery\Entities\CandidateEntity::create( 'joomla/http', '~3', static function (string $class = '\Joomla\Http\Http') { return new $class; } ) ); ``` ### Health Score 13 — LowBetter than 1% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity4 Limited adoption so far Community7 Small or concentrated contributor base Maturity19 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://avatars.githubusercontent.com/u/16020878?v=4)[Artem Vasilev](/maintainers/kernusr)[@kernusr](https://github.com/kernusr) --- Top Contributors [![kernusr](https://avatars.githubusercontent.com/u/16020878?v=4)](https://github.com/kernusr "kernusr (6 commits)") ### Embed Badge ![Health badge](/badges/webmasterskaya-php-kladr-api/health.svg) ``` [![Health](https://phpackages.com/badges/webmasterskaya-php-kladr-api/health.svg)](https://phpackages.com/packages/webmasterskaya-php-kladr-api) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)