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
Где:
token - токен для доступа к API;
addressText - непосредственно описание адреса.
Помимо обязательных параметров есть и дополнительные, например, режим поиска, количество ответов.
В ответ получим массив элементов следующей структуры:
[
"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 метод по выдаче уровней в ближайшее время.
С остальными примерами методов можно ознакомиться в технической документации (см. ссылку выше).