API для ввода адреса в структурированном виде (в формате ГАР ФИАС)
API: Сервис для ввода адресов — инструмент, который обеспечивает доступ к базе адресов государственного адресного реестра (ГАР БД ФИАС). API предлагает уникальный метод по работе с адресами в формате муниципального и административного деления.
Для чего API: Сервис для ввода адресов?
API автоматически подгружает адрес по первым буквам, разбирает адрес на составные части: от региона до квартиры, выводит адрес в правильном порядке и исключает опечатки.
Как работает «API: Сервис для ввода адресов»
В чем уникальность API?
Уникальность в том, что на рынке присутствуют API, которые предоставляют доступ только к адресам административно-территориального деления. А вот обработки адресов по муниципальному делению не было до реализации API: Сервис для ввода адресов.
Также API предлагает возможность получения списка нижестоящих частей адресов по уровням, то есть, например, нужно узнать какие есть городские районы в городе Москва, или получить список домов в определенном регионе города Москвы, ну и т.д.
Кроме того не было возможности получить идентификатор адресообразующего элемента по полному адресу вплоть до квартиры, с внедрением API такая возможность появляется.
В остальном «API: Сервис для ввода адресов» выполняет похожие функции, как и у других API, например, как у dadata.
C полным списком функциональных возможностей можно ознакомиться в технической документации.
Как внедрить?
Доступ к БД осуществляется двумя HTTP-запросами: POST и GET. Выбор зависит от того, как Вам будет удобно использовать. Структура ответа похожа, но есть небольшие отличия:
Метод POST разрабатывался специально для тех, у кого уже внедрена работа с адресами другого API, то есть для быстрого перехода.
Метод же GET возвращает больше параметров, тем самым решая, например, проблему с адресным идентификатором до квартиры.
Как использовать API?
Самым распространенным применением API является помощь пользователю при вводе адреса в текстовом поле, так называемый полнотекстовый поиск. Причем поиск, как и говорилось ранее, будет происходить при вводе адреса в виде административного деления, так и в виде муниципального деления.
Пример такого GET-запроса на получение вариантов полного адреса объекта по указанному приблизительному тексту:
https://data.pbprog.ru/api/address/full-address/parse? token=123abcde123abcde123adcde123abcde123abcde&addressText=Киров,%20Ленина,%20113
Где:
Помимо обязательных параметров есть и дополнительные, например, режим поиска, количество ответов.
В ответ получим массив элементов следующей структуры:
[
"value": "Калужская обл, Кировский р-н, г Киров, ул Ленина, д 113",
"addressParts": [
{
"objectGuid": "18133adf-90c2-438e-88c4-62c41656de70",
"name": "Калужская",
"typeName": "обл",
"fullTypeName": "область",
"level": 1,
"kladr": "4000000000000",
"okato": "29000000000",
"oktmo": "29000000",
"isActive": true
},
{
"objectGuid": "bd20192d-2702-4d5f-bd0c-7db4df7be215",
"name": "Кировский",
"typeName": "р-н",
"fullTypeName": "район",
"level": 2,
"isActive": true
},
{
"objectGuid": "7c875ac0-5c75-4798-8786-564ccb5bd9f2",
"name": "Киров",
"typeName": "г",
"fullTypeName": "город",
"level": 5,
"kladr": "4001100100000",
"okato": "29214501000",
"oktmo": "29614101001",
"isActive": true
},
{
"objectGuid": "3ebd4a60-3f08-4d89-83a8-1f0feaea4760",
"name": "Ленина",
"typeName": "ул",
"fullTypeName": "улица",
"level": 8,
"kladr": "40011001000005200",
"okato": "29214501000",
"oktmo": "29614101001",
"postIndex": "249440",
"isActive": true
},
{
"objectGuid": "7db78665-c605-45b9-8d74-ea5e3fc0176b",
"name": "113",
"typeName": "д",
"fullTypeName": "дом",
"level": 10,
"okato": "29214501000",
"oktmo": "29614101001",
"postIndex": "249440",
"isActive": true
}
]
},
},
...
]В данном примере присутствуют следующие элементы:
value — непосредственно адрес;
addressParts — массив с детальной информацией по элементам адреса, в который входят:
GUID объекта;
Наименование;
Сокращенное и полное название типа элемента;
Уровень вложенности;
Код КЛАДР, ОКАТО, ОКТО;
Почтовый индекс;
Признак активности.
Реальный примертакой реализации ввода адресов Вы можете посмотреть по ссылке → https://pbprog.ru/lp/fias/.
После получения ответа все что Вам остается разложить его в нужном Вам формате и виде.
Например:
Но есть еще вариант использования API — расширенный поиск адреса.
Например, реализация в виде формы ввода адреса как на официальном сайте ФИАС. (https://fias.nalog.ru/ExtendedSearch).
Если для решения вашей задачи стоит реализовать возможность расширенного поиска адреса, то «API: Сервис для ввода адресов» Вам в этом поможет.
Вам нужно:
Сформировать запрос на получение регионов РФ.
Пример запроса:
https://data.pbprog.ru/api/address/regions? token=123abcde123abcde123adcde123abcde123abcde&activeOnly=false
В ответ получим массив элементов вида:
{
"regionCode":"01",
"objectGuid":"d8327a56-80de-4df2-815c-4f6ab1224c50",
"name":"Адыгея",
"typeName":"Респ",
"fullTypeName":"Республика",
"kladr":"0100000000000",
"okato":"79000000000",
"oktmo":"79000000",
"postIndex":"385000"
}где:
regionCode — код региона;
objectGuid — GUID ФИАС региона;
name — название региона;
typeName — сокращенное название типа региона;
fullTypeName — полное название типа региона;
kladr — код КЛАДР;
okato — код ОКАТО;
oktmo — код ОКТМО;
postIndex — почтовый индекс.
Из полученного массива элементов заполнить первое поле со списком.
Все остальная работа контролов зависит от выбранного родительского элемента.
То есть, выбрали регион, получили GUID объекта. И далее по этому GUID получаете список, например, муниципальных районов.
Пример запроса для получения районов Кировской области:
https://data.pbprog.ru/api/address/childs/0b940b96–103f-4248–850c-26b6c7296728? token={123abcde123abcde123adcde123abcde123abcde}&hierarchyMode=adm
В ответ получим массив элементов вида:
{
"objectGuid": "c33ab87d-1f10-4eb9-a628-ab06a9fdf08b",
"name": "67",
"typeName": "д",
"fullTypeName": "дом",
"level": 10,
"okato": "79230559000",
"oktmo": "79630159051",
"postIndex": "385140",
"isActive": true,
"sublevels": [
{
"name": "1",
"typeName": "к",
"fullTypeName": "корпус"
},
{
"name": "67",
"typeName": "стр",
"fullTypeName": "строение"
}
]
}
где:
objectGuid — GUID ФИАС элемента.
name — название элемента.
typeName — сокращенное название типа элемента.
fullTypeName — полное название типа элемента.
level — уровень типа элемента.
okato — код ОКАТО.
oktmo — код ОКТМО.
postIndex — почтовый индекс.
isActive — признак активности.
sublevels — доп. уровни адреса. Применимо только к домам. Максимум до 2-х доп. уровней.
и так далее до нужного уровня.
Но! Есть тонкость в реализации. У каждого контрола необходимо определить свой уровень и при разборе ответа заполнять соответствующие элементы.
Сами уровни представлены ниже.
level | name |
1 | Субъект РФ |
2 | Административный район |
3 | Муниципальный район |
4 | Сельское/городское поселение |
5 | Город |
6 | Населенный пункт |
7 | Элемент планировочной структуры |
8 | Элемент улично-дорожной сети |
9 | Земельный участок |
10 | Здание (сооружение) |
11 | Помещение |
12 | Помещения в пределах помещения |
13 | Уровень автономного округа (устаревшее) |
14 | Уровень внутригородской территории (устаревшее) |
15 | Уровень дополнительных территорий (устаревшее) |
16 | Уровень объектов на дополнительных территориях (устаревшее) |
17 | Машино-место |
Изменение идентификаторов уровней в ГАР БД ФИАС маловероятны. Но, мы обещаем добавить в API метод по выдаче уровней в ближайшее время.
С остальными примерами методов можно ознакомиться в технической документации (см. ссылку выше).
