Сервис предоставляет он-лайн интерфейс к базе адресов Российской Федерации(«ФИАС»). Обмен данными
происходит в формате JSON, с поддержкой JSONP.
Для облегчнения интеграции разработаны плагины под разные плаформы, которые подробно описаны ниже
на этой странице. Плагины распространяются бесплатно под лицензией «Public domain», без каких-либо
ограничений на использование.
Основные возможности:
Искать регионы, нас. пункты, улицы, дома по подстроке и по коду
Фильтровать данные по регионам, нас. пунткам и улицам
Получать сведения о родительских элементах и почтовых индексах
Например, можно попросить сервис вернуть все города на букву «А», или все улицы Москвы начинающиеся
на «Лен».
contentType — Тип возвращаемых объектов (region, district, city, street, building)
withParent — Если 1, сервис вернёт объекты вместе с родительскими (для района это регион, для населённого пункта район и регион и т.п.)
limit — Количество возвращаемых объектов
offset — Смещение в выдаче (для организации постраничного вывода)
typeCode — Тип объектов для выдачи:
1 — города
2 — поселки
4 — деревни
Битовые комбинации, например, 3 ( 1 | 2 ) — города и поселки
zip — Почтовый индекс. Работает только при contentType = building. В этом случае можно не передать parentId. Поиск по почтовому индексу — это поиск по строениям (building), поэтому логично указать withParent = 1 и limit = 1, чтоб выбрать данные о регионе, нас. пункте и т.п.
Например: http://kladr-api.ru/api.php?contentType=building&limit=1&withParent=1&zip=163000
oneString — Поиск адреса одной строкой в свободной форме. С этим параметром используются:
query — строка поиска
withParent=1 — выводить сведения о родителях
limit — кол-во результатов в выдаче
regionId, districtId, cityId — фильтры для ограничения поиск
{
"searchContext": { // Объект с переданными серверу параметрами
"query": "Арх",
"contentType": "city",
"withParent": 1,
"limit": 2
},
"result": [ // Массив полученных объектов заданного типа (населённые пункты)
{
"id": "2900000100000", // Код объекта
"name": "Архангельск", // Название объекта
"zip": null, // Почтовый индекс объекта
"type": "Город", // Тип объекта полностью
"typeShort": "г", // Тип объекта коротко
"okato": "11401000000", // Код ОКАТО
"parents": [ // Массив родительских объектов (если был передан параметр withParent)
{
"id": "2900000000000",
"name": "Архангельская",
"zip": null,
"type": "Область",
"typeShort": "обл",
"okato": "11000000000",
"contentType": "region"
}
]
},
{
"id": "2800200000100",
"name": "Архара",
"zip": "676740",
"type": "Поселок городского типа",
"typeShort": "пгт",
"okato": "10205551000",
"parents": [
{
"id": "2800000000000",
"name": "Амурская",
"zip": "675000",
"type": "Область",
"typeShort": "обл",
"okato": "10000000000",
"contentType": "region"
},
{
"id": "2800200000000",
"name": "Архаринский",
"zip": null,
"type": "Район",
"typeShort": "р-н",
"okato": "10205000000",
"contentType": "district"
}
]
}
]
}
Особенности поиска объектов
Поиск объектов осуществляется либо по названию либо по коду связанного (родительского либо дочернего элемента).
Поиск объектов по названию осуществляется по шаблону /^название/ (т.е. выбираются объекты, название которых полностью
совпадает с поисковой строкой либо начинается на неё).
type - перечисление используемых типов объектов. Список значений: region, district, city, street, building
api= function( query, callback ) {} - функция непосредственно выполняющая запрос к сервису. В качестве параметров принимает объект запроса и функцию, которой будет передан ответ сервиса.
check= function( query, callback ) {} - функция для проверки существования объекта. В качестве параметров принимает объект запроса и функцию, которой будет передан объект (если он существует) либо false
Параметры плагина
token - токен для доступа к сервису, обязательный параметр
key – ключ для доступа к сервису, обязательный параметр
type – тип подставляемых объектов, обязательный параметр
parentType – тип родительского объекта, по-умолчанию null
source = function( query ) { return objects; } - функция для получения списка объектов отображаемых при автодополнении. По-умолчанию запрашивает данные у сервиса. Может быть переопределена для получения объектов из другого источника.
labelFormat = function( obj, query) { return label; } - функция для форматирования значений в списке. В качестве параметров принимает obj – объект КЛАДР, query – текущее значение поля ввода.
valueFormat = function( obj, query) { return label; } – функция для форматирования подставляемых в поле ввода значений. В качестве параметров принимает obj – объект КЛАДР, query – текущее значение поля ввода.
События плагина
open = function() {} - открыт список объектов. Доступно как событие kladr_open поля ввода.
close = function() {} - закрыт список объектов. Доступно как событие kladr_close поля ввода.
send = function() {} - отправлен запрос к сервису. Доступно как событие kladr_send поля ввода.
received = function() {} - получен ответ от сервиса. Доступно как событие kladr_received поля ввода.
select = function( obj ) {} - выбран объект в списке. В параметре передаётся текущий, выбранный объект КЛАДР. Доступно как событие kladr_select поля ввода.
check = function( obj ) {} - проверен введённый пользователем объект. Вызывается только если параметр verify = true. В параметре передаётся текущий объект КЛАДР. Доступно как событие kladr_check поля ввода.
QueryToJson(Query $query) - выполняет запрос к сервису, возвращая данные в виде объекта Json
QueryToArray(Query $query) - выполняет запрос к сервису, возвращая данные в виде ассоциативного массива
QueryToObjects(Query $query) - выполняет запрос к сервису, возвращая данные в виде массива объектов
Свойства:
Error - текст последней, возникшей при обращении к сервису, ошибки
Объект запроса — Kladr\Query
Свойства:
ParentType - тип родительского объекта для ограничения области поиска (регион, район, город)
ParentId - идентификатор родительского объекта для ограничения области поиска
ContentType - тип искомого объекта (регион, район, город)
ContentName - название искомого объекта
WithParent - получить объекты вместе с родителями (если true у объекта заполняется свойство Parent)
Limit - ограничение количества возвращаемых объектов
Объект базы — Kladr\Object
Свойства:
Id - идентификатор объекта
Name - название объекта
Zip - почтовый индекс объекта
Type - подпись объекта полностью (область, район)
TypeShort - подпись объекта коротко (обл, р-н)
Parents - массив родительских объектов (заполняется если в запросе был установлен флаг WithParent)
Перечисление типов объектов, используемых в запросах к сервису — Kladr\ObjectType
Константы:
Region - регион
District - район
City - населённый пункт
Street - улица
Building - строение
Примеры
Получение списка всех населённый пунктов, название которых начинается на "Арх"
// Инициализация api, в качестве параметров указываем токен и ключ для доступа к сервису
$api = new Kladr\Api('51dfe5d42fb2b43e3300006e', '86a2c2a06f1b2451a87d05512cc2c3edfdf41969');
// Формирование запроса
$query = new Kladr\Query();
$query->ContentName = 'Арх';
$query->ContentType = Kladr\ObjectType::City;
$query->WithParent = true;
$query->Limit = 2;
// Получение данных в виде ассоциативного массива
$arResult = $api->QueryToArray($query);
Модуль 1С-Битрикс предоставляющий форму для ввода адреса с автодополнением. В качестве источника данных используется сервис «КЛАДР в облаке»
Установка
Загрузите модуль
Скопируйте в папку «/bitrix/modules» вашего сайта
Переименуйте модуль в primepixkladr
Установите модуль
Разместите компонент «Форма для ввода адреса» на странице для ввода адреса
В настройках компонента укажите токен и ключ для подключения к сервису «КЛАДР в облаке»
Параметры компонента «Форма для ввода адреса»
Основные параметры
Токен для доступа к КЛАДР API - токен для доступа к сервису
Ключ для доступа к КЛАДР API - ключ для доступа к сервису
Выводить поля для ввода
Области – Добавляет поле с именем «region» для ввода названия области
Района – Добавляет поле с именем «district» для ввода названия района
Населённого пункта – Добавляет поле c именем «location» для ввода названия населённого пункта
Улицы – Добавляет поле c именем «street» для ввода названия улицы
Дома – Добавляет поле с именем «building» для ввода номера дома
Выводить скрытые поля
Код объекта – добавляет скрытое поле с именем «kladr_id», в которое по окончанию ввода адреса будет записан его код
Почтовый индекс – добавляет скрытое поле с именем «zip_code» в которое по окончанию ввода адреса будет записан его почтовый индекс из КЛАДР
Подписи – добавляет скрытое поле с постфиксом «_label» к каждому полю ввода в которое будет записана подпись к введённому пользователем значению (например: город, посёлок, село)
Сокращения подписей – добавляет скрытое поле к постфиксом «_label_min» к каждому полю ввода, в которое будет записано сокращение подписи к введённому пользователем значению (г., пос., с.)
Опции
Обновлять подписи при вводе – Включает обновление подписей к полям ввода. Например, если пользователь в поле город введёт «Москва», то подпись «Населённый пункт» автоматически будет изменена на «Город»
Удалять значения, которых нет в КЛАДР – Включает проверку ввода в поля адреса и удаление ошибочно введённых значений. Например, если пользователь введёт в поле «Населённый пункт» значение «Мухосранск», то оно будет автоматически удалено, т.к. населённого пункта «Мухосранск» в России нет.
Дополнительные параметры
Подключить jQuery – Компонент использует библиотеку jQuery, поэтому если она не используется у вас на сайте включите данный пункт
Подключить jQuery UI – Компонент использует библиотеку jQuery UI, поэтому если она не используется у вас на сайте включите данный пункт
Подключить тему jQuery UI – Компонент использует тему jQuery UI для автодополнения адреса. Если она не используется у вас на сайте включите данный пункт
Результат
Компонент выводит на сайт несколько текстовых и скрытых полей для ввода адреса. Компонент не генерирует формы (<form></form>) для отправки на сервер введённой пользователем информации!
Это сделано для того чтобы вы без проблем могли включить поля для ввода адреса в любую другую существующую форму на вашем сайте (к примеру форму оформления заказа).