API для ввода адреса в структурированном виде по ГАР ФИАС

Полигон: API Адрес — инструмент, который обеспечивает доступ к базе адресов государственного адресного реестра (ГАР БД ФИАС). API предлагает уникальный метод по работе с адресами в формате муниципального и административного деления.

Подключить бесплатно →

---

Как сервис улучшает жизнь?

API автоматически подгружает адрес по первым буквам, разбирает адрес на составные части: от региона до квартиры, выводит структурированный адрес – в правильном порядке и без опечаток.

Что такое структурированный адрес?

Когда адрес разложен «по полочкам»:

1. Правильный порядок адреса

2. Дополнительная информация (код ГАР ФИАС, ОКАТО, КЛАДР, ОКТМО, почтовый индекс и др.)

В чем уникальность API? 

До недавнего времени на рынке присутствовали API, которые предоставляли доступ только к адресам административно-территориального деления. А вот обработки адресов по муниципальному делению не было – до реализации API: Сервис для ввода адресов в котором присутствует подобная возможность.

Также в API можно получить список нижестоящих частей адресов по уровням: например, если нужно узнать городские районы в городе Москва, или получить список домов в определенном регионе городы Москвы.

Кроме того, до реализации сервиса, на рынке было затруднительно получить идентификатор адресообразующего элемента по полному адресу вплоть до квартиры. С внедрением API такая возможность появилась.

В остальном API: Сервис для ввода адресов выполняет функции, как и у других подобных сервисов. C полным списком возможностей API можно ознакомиться в технической документации →

Как внедрить?

Доступ к БД осуществляется двумя 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 объекта;

• Наименование;

• Сокращенное и полное название типа элемента;

• Уровень вложенности;

• Код КЛАДР, ОКАТО, ОКТО;

• Почтовый индекс;

• Признак активности.

---

Реальный пример описанной реализации ввода адресов Вы можете посмотреть по ссылке →

---

После получения ответа необходимо разложить адрес в нужном Вам формате и виде.

Например:

Но есть и другой способ использования API – расширенный поиск адреса. Например в форме, представленной на официальном сайте ФИАС.

Если для решения ваших задач необходим расширенный поиск адреса, воспользуйтесь – API: Сервис для ввода адресов.

Вам необходимо:

1. Сформировать запрос на получение регионов РФ.

Пример запроса: 

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 Вы получаете список, например, муниципальных районов.

Пример запроса для получения районов Кировской области: 

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	Машино-место

С остальными примерами методов можно ознакомиться в технической документации →