Документация

Есть два варианта подключения ФИАС в облаке: к своему сайту через jQuery плагин
или к своему серверу при помощи нашего API
image
image
image

Мы храним базу ФИАС в собственном формате, оптимизированным для быстрого поиска. Для бесперебойной работы используем несколько серверов в облаке Mail.ru.

kladr-api.ru/api.php

Токен

Доступ к бесплатным и платным серверам

После регистрации в личном кабинете вы увидете свой уникальный токен.

Платные сервера

https://kladr-api.com/api.php

Всегда необходимо указывать свой токен в параметре token.

Бесплатные сервера

https://kladr-api.ru/api.php

Токен указывать необязательно.

Интеграция с сайтом

Установите и настройте jQuery-плагин fias-api / jquery

Документация о настройке плагина находится на его github странице.

По умолчанию плагин настроен на работу с бесплатным сервером. Для работы с платным сервером добавьте свой токен и укажите URL платного сервера следующим образом:

<script type="text/javascript">
    $.fias.token = 'ваш токен';
    $.fias.url = 'https://kladr-api.com/api.php';
</script>

Подключение к серверу (API)

Доступ к API является публичным, без каких-либо ограничений. Бесплатные сервера предоставляются как есть, мы не гарантируем их работоспособность и скорость ответа. Бесплатный API отлично подходит, например, для тестирования сервиса, личного использования, домашних страниц. Доступ к платным серверам возможен только при указании вашего токена, который мы активируем после оплаты.

Параметры запроса

  • Адрес страницы для запроса к платным серверам:   
    https://kladr-api.ru/api.php
  • Адрес страницы для запроса бесплатной версии:
    https://kladr-api.com/api.php



Плагины

Для облегчнения интеграции разработаны плагины под разные плаформы. Скачать их можно бесплатно.

Параметры API-запроса

Все параметры передаются через GET-параметры
token
Токен для доступа к сервису. При регистрации выдается бесплатный токен. Получить доступ к платным серверам можно здесь
regionId
Код региона (области)
districtId
Код района
cityId
Код города (населённого пункта)
streetId
Код улицы
buildingId
Код дома (строения)
query
Строка для поиска по названию
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, чтоб выбрать данные о регионе, нас. пункте и т. п.
oneString
Поиск адреса одной строкой в свободной форме. С этим параметром используются:
  • query
    Строка поиска
  • withParent=1
    Выводить сведения о родителях
  • limit
    Кол-во результатов в выдаче
  • regionId, districtId, cityId
    Фильтры для ограничения поиск
callback
JavaScript метод которому будет передан ответ базы

Формат ответа сервиса

{
    "searchContext": {                      // Объект с переданными серверу параметрами
    "query": "Арх",
        "contentType": "city",
        "withParent": 1,
        "limit": 2
},
    "result": [                             // Массив полученных объектов заданного типа (населённые пункты)
    {
        "id": "2900000100000",          // КЛАДР Код объекта
        "name": "Архангельск",          // Название объекта
        "zip": null,                    // Почтовый индекс объекта
        "type": "Город",                // Тип объекта полностью
        "typeShort": "г",               // Тип объекта коротко
        "okato": "11401000000",         // Код ОКАТО
        "oktmo": "11701000",            // Код ОКТМО
        "guid": "06814fb6-0dc3-4bec-ba20-11f894a0faf5",             // ФИАС Код объекта,
        "parentGuid": "294277aa-e25d-428c-95ad-46719c4ddb44",       // ФИАС Код родителя
        "cadnum": "",                   // Кадастровый номер,
        "ifnsfl": "2901",               // Код налоговой
        "ifnsul": "2901",               // Код налоговой
        "parents": [                    // Массив родительских объектов (если был передан параметр withParent)
            {
                "id": "2900000000000",
                "name": "Архангельская",
                "zip": null,
                "type": "Область",
                "typeShort": "обл",
                "okato": "11000000000",
                "conentType": "region",
                "okato": "11401000000",
                "oktmo": "11701000",
                "guid": "06814fb6-0dc3-4bec-ba20-11f894a0faf5",
                "parentGuid": "294277aa-e25d-428c-95ad-46719c4ddb44"

            }
        ]
    },
    {
        "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"
            }
        ]
    }
]
}

Особенности поиска объектов

Поиск объектов осуществляется либо по названию либо по коду связанного (родительского либо дочернего элемента). Поиск объектов по названию осуществляется по шаблону /^название/ (т. е. выбираются объекты, название которых полностью совпадает с поисковой строкой либо начинается на неё).

Для поиска улицы по названию необходимо обязательно указать код населённого пункта.

Для поиска строения по названию необходимо обязательно указать код улицы.