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

⚠️ В большинстве случаев вам нужен не этот метод, а подсказки по адресам

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

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

Как вызвать

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

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

            
                POST http://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/fias
            
            
                
                    { "query": "москва хабар" }

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

var url = "http://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/fias";
var token = "${API_KEY}";
var query = "москва хабар";

var options = {
    method: "POST",
    mode: "cors",
    headers: {
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Authorization": "Token " + token
    },
    body: JSON.stringify({query: query})
}

fetch(url, options)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log("error", error));

// https://github.com/hflabs/dadata-php

$token = "${API_KEY}";
$dadata = new \Dadata\DadataClient($token, null);
$result = $dadata->suggest("fias", "москва хабар");

# https://github.com/hflabs/dadata-py

from dadata import Dadata
token = "${API_KEY}"
dadata = Dadata(token)
result = dadata.suggest("fias", "москва хабар")

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

Content-Type: application/json.
Accept: application/json.
${API_KEY} — API-ключ.

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

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

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

Что в ответе

Объект с массивом подсказок в поле 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": null,
                "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 символов.

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

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

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

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

По адресам

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

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

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

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

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

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

Общие

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

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

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

Что будет, если превысить 10 000 бесплатных запросов в день?

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

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

Стоимость

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