webmasterskaya/php-kladr-api

Maintainers

Details

github.com/webmasterskaya/php-kladr-api

Source

Issues

Installs: 0

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 0

dev-master 2024-02-12 09:54 UTC

Requires

Requires (Dev)

MIT 76970cf6eded9bde89c3fae8b801db2f3251ad68

This package is auto-updated.

Last update: 2024-04-12 10:41:05 UTC

README

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"=> ""
        ]
      ]
    ]
  ]
]

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

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

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

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

Пример регистрации 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;
        }
    )
);