↑ API подсказок

API подсказок по ФИАС

Ищет адреса строго по ФИАС. Используйте эти подсказки только в том случае, если твёрдо уверены, что вам нужны именно они. Для большинства задач намного лучше подходят подсказки по адресам — они более полные, логичные и удобные. Подсказки по ФИАС нужны только если вам по какой-то причине важно точное, побуквенное соответствие справочнику адресов налоговой службы.

Если слова «ФИАС» и «планировочная структура» вам ничего не говорят — пожалуйста, не используйте эти подсказки. Используйте подсказки по адресам.

Как вызвать

Чтобы вызвать метод, зарегистрируйтесь и подтвердите почту.

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

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "Authorization: Token ${API_KEY}" \
    -d '{ "query": "москва хабар", "count": 10 }' \
    https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/fias

Укажите при вызове:

  • Content-Type: application/json или application/xml.
  • Accept — аналогично.
  • ${API_KEY} — API-ключ.

Тело запроса передавайте в кодировке UTF-8.

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

Название Обязательный? По умолчанию Описание
query Текст запроса
count 10 Количество результатов (максимум — 20)
locations Ограничение области поиска
locations_boost Приоритет города при ранжировании
from_bound
to_bound
Гранулярные подсказки по ФИАС

Что в ответе

Объект с массивом подсказок в поле suggestions:

Пример ответа
{
    "suggestions": [
        {
            "value": "г Москва, ул Хабаровская",
            "unrestricted_value": "г Москва, ул Хабаровская",
            "data": {
                "postal_code": null,
                "region_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
                "region_kladr_id": "7700000000000",
                "region_with_type": "г Москва",
                "region_type": "г",
                "region_type_full": "город",
                "region": "Москва",
                "area_fias_id": null,
                "area_kladr_id": null,
                "area_with_type": null,
                "area_type": null,
                "area_type_full": null,
                "area": null,
                "city_fias_id": null,
                "city_kladr_id": null,
                "city_with_type": null,
                "city_type": null,
                "city_type_full": null,
                "city": null,
                "city_district_fias_id": null,
                "city_district_kladr_id": null,
                "city_district_with_type": null,
                "city_district_type": null,
                "city_district_type_full": null,
                "city_district": null,
                "settlement_fias_id": null,
                "settlement_kladr_id": null,
                "settlement_with_type": null,
                "settlement_type": null,
                "settlement_type_full": null,
                "settlement": null,
                "planning_structure_fias_id": null,
                "planning_structure_kladr_id": null,
                "planning_structure_with_type": null,
                "planning_structure_type": null,
                "planning_structure_type_full": null,
                "planning_structure": null,
                "street_fias_id": "32fcb102-2a50-44c9-a00e-806420f448ea",
                "street_kladr_id": "77000000000713400",
                "street_with_type": "ул Хабаровская",
                "street_type": "ул",
                "street_type_full": "улица",
                "street": "Хабаровская",
                "house_fias_id": null,
                "house_kladr_id": null,
                "house_type": null,
                "house": null,
                "block": null,
                "building_type": null,
                "building": null,
                "fias_id": "32fcb102-2a50-44c9-a00e-806420f448ea",
                "fias_code": "7700000000000007134",
                "fias_level": "7",
                "fias_actuality_state": "0",
                "kladr_id": "77000000000713400",
                "capital_marker": "0",
                "okato": "45263564000",
                "oktmo": "45305000",
                "cadastral_number": null,
                "tax_office": "7718",
                "tax_office_legal": "7718",
                "history_values": [
                    "ул Черненко"
                ],
                "source": null,
                "qc": null
            }
        },
        ...
    ]
}
Название Описание
value Адрес одной строкой (как показывается в списке подсказок)
unrestricted_value Адрес одной строкой (полный, с индексом)
data.postal_code Индекс
data.region_fias_id Код ФИАС региона
data.region_kladr_id Код КЛАДР региона
data.region_with_type Регион с типом
data.region_type Тип региона (сокращенный)
data.region_type_full Тип региона
data.region Регион
data.area_fias_id Код ФИАС района в регионе
data.area_kladr_id Код КЛАДР района в регионе
data.area_with_type Район в регионе с типом
data.area_type Тип района в регионе (сокращенный)
data.area_type_full Тип района в регионе
data.area Район в регионе
data.city_fias_id Код ФИАС города
data.city_kladr_id Код КЛАДР города
data.city_with_type Город с типом
data.city_type Тип города (сокращенный)
data.city_type_full Тип города
data.city Город
data.city_district_fias_id Код ФИАС района города (заполняется, только если район есть в ФИАС)
data.city_district_kladr_id Код КЛАДР района города (не заполняется)
data.city_district_with_type Район города с типом
data.city_district_type Тип района города (сокращенный)
data.city_district_type_full Тип района города
data.city_district Район города
data.settlement_fias_id Код ФИАС нас. пункта
data.settlement_kladr_id Код КЛАДР нас. пункта
data.settlement_with_type Населенный пункт с типом
data.settlement_type Тип населенного пункта (сокращенный)
data.settlement_type_full Тип населенного пункта
data.settlement Населенный пункт
data.planning_structure_fias_id Код ФИАС план. структуры
data.planning_structure_kladr_id Код КЛАДР план. структуры
data.planning_structure_with_type Планировочная структура с типом
data.planning_structure_type Тип планировочной структуры (сокращенный)
data.planning_structure_type_full Тип планировочной структуры
data.planning_structure Планировочная структура
data.street_fias_id Код ФИАС улицы
data.street_kladr_id Код КЛАДР улицы
data.street_with_type Улица с типом
data.street_type Тип улицы (сокращенный)
data.street_type_full Тип улицы
data.street Улица
data.house_fias_id Код ФИАС дома
data.house_kladr_id Код КЛАДР дома
data.house_type Тип дома
data.house Дом
data.block Корпус
data.building_type Тип строения
data.building Строение
data.cadastral_number Кадастровый номер
data.fias_id Код ФИАС:
  • HOUSE.HOUSEGUID для домов;
  • ADDROBJ.AOGUID для улиц и вышестоящих объектов.
data.fias_code Иерархический код адреса в ФИАС (СС+РРР+ГГГ+ППП+СССС+УУУУ+ДДДД)
data.fias_level Уровень адреса по ФИАС:
  1 — регион
  3 — район
  4 — город
  5 — район города
  6 — населенный пункт
  7 — улица
  8 — дом
 65 — планировочная структура
data.fias_actuality_state Признак актуальности адреса в ФИАС
  0    — актуальный
  1–50 — переименован
  51   — переподчинен
  99   — удален
data.kladr_id Код КЛАДР
data.capital_marker Признак центра района или региона:
  1 — центр района
      (Московская обл, Одинцовский р-н, г Одинцово)
  2 — центр региона
      (Новосибирская обл, г Новосибирск)
  3 — центр района и региона
      (Томская обл, г Томск)
  4 — центральный район региона
      (Тюменская обл, Тюменский р-н)
  0 — ничего из перечисленного
      (Московская обл, г Балашиха)
data.okato Код ОКАТО
data.oktmo Код ОКТМО
data.tax_office Код ИФНС для физических лиц
data.tax_office_legal Код ИФНС для организаций
data.history_values[ ] Список исторических названий объекта нижнего уровня.
Если подсказка до улицы — это прошлые названия этой улицы, если до города — города.
Не заполняются
data.source
data.qc

Источник данных: Федеральная информационная адресная система (ФИАС) Налоговой службы.

Коды ответа на запрос

HTTP-код ответа Описание
200 Запрос успешно обработан
400 Некорректный запрос (невалидный JSON или XML)
401 В запросе отсутствует API-ключ
403 В запросе указан несуществующий API-ключ
Или не подтверждена почта
Или исчерпан дневной лимит по количеству запросов
405 Запрос сделан с методом, отличным от POST
413 Слишком большая длина запроса или слишком много условий
429 Слишком много запросов в секунду или новых соединений в минуту
5xx Произошла внутренняя ошибка сервиса

Примеры вызова

Заголовки и параметры

Ограничение сектора поиска

Гранулярные подсказки

Ограничения

Количество условий в параметрах locations и locations_boost — не более 10.

Длина запроса (параметр query) — не более 300 символов.

Количество запросов в день — в соответствии с тарифным планом.

Максимальная частота запросов — 20 в секунду.

Максимальная частота создания новых соединений — 60 в минуту.

Частые вопросы

По адресам

Почему вернулся неправильный КЛАДР-код дома?

Подсказки работают по справочнику адресов налоговой службы (ФИАС).
В ФИАС нет кодов КЛАДР для домов.

Поэтому код дома (последние четыре цифры в коде КЛАДР) подсказки берут из поля «Счетчик записей домов для КЛАДР 4» (COUNTER). Эти коды часто отличаются от указанных в КЛАДРе.

Впрочем, в самом КЛАДРе с каждым обновлением базы коды домов меняются, поэтому использовать их в качестве «постоянного» идентификатора адреса невозможно.

Как часто обновляется справочник адресов (ФИАС)?

Один раз в неделю, на выходных.

Общие

Подсказки не работают: ошибка 403 Forbidden (Feature SUGGESTIONS disabled for token)

Возможные причины:

  • Не подтверждён адрес эл. почты. Проверьте в личном кабинете. Если почта не подтверждена — посмотрите почтовый ящик и папку «спам», там должно быть письмо от «Дадаты».
  • В запросе указан неправильный API-ключ. Проверьте в личном кабинете
  • Исчерпан лимит запросов на день. Проверьте в личном кабинете
  • Вы делаете запросы с сервера, при этом настроена привязка к домену. Отключите привязку к домену, либо делайте запросы из браузера.
Что будет, если превысить 10 000 бесплатных запросов в день?

Подсказки перестанут подсказывать ツ До начала нового дня, затем снова заработают.

10 000 запросов считаются суммарно по всем видам подсказок: адреса, ФИО, организации, банки, емейлы...

Как защитить API-ключ от злоумышленников?

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

Если вы подключили Подсказки не через jQuery-плагин, а из программы через API, злоумышленник не сможет подсмотреть ключ. В этом случае привязка к домену не требуется.

Если вы используете и jQuery-плагин, и работу через API — привязку к домену придётся отключить (иначе она «не пропустит» API-запросы). Мы рекомендуем использовать что-то одно — или плагин, или API — но не оба способа одновременно.

Стоимость

Бесплатно до 10 тысяч запросов в день. Больше — в составе годовой подписки.

ajax-spinner

Зарегистрируйтесь, чтобы подключить подсказки

до 10 тыс. запросов бесплатно

чтобы обращаться к вам в письмах

Регистрируясь, вы принимаете публичную оферту

Уже зарегистрированы? Войти