webmasterskaya/php-kladr-api

维护者

详细信息

github.com/webmasterskaya/php-kladr-api

源代码

问题

安装: 2

依赖: 0

建议者: 0

安全: 0

星级: 1

关注者: 1

分支: 1

开放问题: 0

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

Requires

Requires (Dev)

MIT 76970cf6eded9bde89c3fae8b801db2f3251ad68

This package is auto-updated.

Last update: 2024-09-12 11:31:36 UTC

README

PHP API 用于 与 "ФИАС в облаке" 服务集成。该 SDK 有助于更快地将与俄罗斯所有邮政地址的最新数据库的交互工具集成到您的项目中。

"ФИАС в облаке" — 俄罗斯所有邮政地址的最新数据库。易于与您的网站集成，帮助消除地址书写错误，使整个过程快速方便。

适用于在线商店、邮政和快递服务、微型金融以及需要客户填写地址的网站。

开始之前

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);

该方法将返回包含搜索短语的对象列表数组。有关详细信息，请参阅 "服务响应" 部分

注意 如果在 $query 中传入“Novgorod”，则返回的响应将包含名称中包含该单词的地区、居民点和街道的地址

参数列表

  • 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中列出

允许的居民点类型

所有可用类型都在类Webmasterskaya\Kladr\Type\Code中列出

服务器的响应

不带父对象的响应示例 
[
    "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"=> ""
        ]
      ]
    ]
  ]
]

自动发现依赖关系

可以点击以下链接了解可以自动发现的库列表

如果自动发现列表中没有您的项目使用的库，则需要手动注册它。有关手动注册依赖关系的更多信息，请参阅手动注册依赖关系

手动注册依赖关系

在Bitrix中注册HttpClient的示例

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

在Joomla中注册HttpClient的示例

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