API: Сервис для ввода адресов – инструмент, который обеспечивает доступ к базе адресов государственного адресного реестра (ГАР БД ФИАС). API предлагает уникальный метод по работе с адресами в формате муниципального и административного деления.
Для чего API: Сервис для ввода адресов улучшает жизнь?
API автоматически подгружает адрес по первым буквам, разбирает адрес на составные части: от региона до квартиры, выводит адрес в правильном порядке и без опечаток.
В чем уникальность API?
Уникальность в том, что на рынке присутствуют API, которые предоставляют доступ только к адресам административно-территориального деления. А вот обработки адресов по муниципальному делению не было до реализации «API: Сервис для ввода адресов».
Также API предлагает возможность получения списка нижестоящих частей адресов по уровням, то есть, например, нужно узнать какие есть городские районы в городе Москва, или получить список домов в определенном регионе городы Москвы, ну и т.д. (показать пример?)
Кроме того не было возможности получить идентификатор адресообразующего элемента по полному адресу вплоть до квартиры, с внедрением API такая возможность появляется. (показать пример?)
В остальном «API: Сервис для ввода адресов» выполняет похожие функции, как и у других API, например, как у dadata.
C полным списком функциональных возможностей можно ознакомиться в технической документации: https://services.pbprog.ru/doc/apiFias/.
Как внедрить?
Доступ к БД осуществляется двумя HTTP-запросами: POST и GET. Выбор зависит от того, как Вам будет удобно использовать. Структура ответа похожа, но есть небольшие отличия:
- Метод POST разрабатывался специально для тех, у кого уже внедрена работа с адресами другого API, то есть для быстрого перехода.
- Метод же GET возвращает больше параметров, тем самым решая, например, проблему с адресным идентификатором до квартиры.
Пример такого 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 - почтовый индекс.
Из полученного массива элементов заполнить первое поле со списком.
2. Все остальная работа контролов зависит от выбранного родительского элемента.
То есть, выбрали регион, получили GUID объекта. И далее по этому GUID получаете список, например, муниципальных районов.
Пример запроса для получения районов Кировской области:
В ответ получим массив элементов вида:
{
"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-х доп. уровней.
и так далее до нужного уровня.
Но! Есть тонкость в реализации. У каждого контрола необходимо определить свой уровень и при разборе ответа заполнять соответствующие элементы.
Сами уровни представлены ниже.
Изменение идентификаторов уровней в ГАР БД ФИАС маловероятны. Но, мы обещаем добавить в API метод по выдаче уровней в ближайшее время.
С остальными примерами методов можно ознакомиться в технической документации (см. ссылку выше).