↑ Как подключить подсказки

Подсказки: адреса

Ищет адреса по любой части адреса от региона до квартиры («самара авроры 7 12» → «443017, Самарская обл, г Самара, ул Авроры, д 7, кв 12»). Также ищет по почтовому индексу («105568» → «г Москва, ул Магнитогорская»).

Что умеет

✔️ Работает по всем странам мира (по России до квартиры, по Беларуси, Казахстану и Узбекистану до дома, по остальным странам — до города). Ищет и показывает результаты как на русском языке («Самара, пр-кт Металлургов»), так и на английском («Russia, gorod Samara, prospekt Metallurgov»).

✔️ Находит актуальные адреса по историческим названиям (Свердловск → Екатеринбург) и синонимам (Питер → Санкт-Петербург).

✔️ Ищет по частичному совпадению («москва болот» → «г Москва, Болотная наб»), но только в последнем слове запроса («мос болот» не найдет).

✔️ Исправляет опечатки («самара авиционная») и запросы в неправильной раскладке («vjcrdf» → «москва»).

✔️ Находит адреса по кадастровому номеру («77:02:0004008:4143») и ФИАС-коду («f26b876b-6857-4951-b060-ec6559f04a9a»).

✔️ Возвращает адреса в административном и муниципальном делениях. Раскладывает выбранный адрес на гранулярные части (от региона до квартиры).

✔️ Поддерживает гранулярные подсказки по отдельным частям адреса (регионы, города, улицы, дома).

✔️ Знает земельные участки («казань красная участок 109в» → «420025, Респ Татарстан, г Казань, Советский р-н, ул Большая Красная (Малые Клыки), уч 109в»)

✔️ Учитывает, где вы находитесь (определяет город по IP-адресу).

Как подключить

  1. Вставьте код из примера на свой сайт.
  2. Profit!
<input id="address" name="address" type="text" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
<link href="http://cdn.jsdelivr.net/npm/suggestions-jquery@22.6.0/dist/css/suggestions.min.css" rel="stylesheet" />
<script src="http://cdn.jsdelivr.net/npm/suggestions-jquery@22.6.0/dist/js/jquery.suggestions.min.js"></script>

<script>
    $("#address").suggestions({
        token: "${API_KEY}",
        type: "ADDRESS",
        /* Вызывается, когда пользователь выбирает одну из подсказок */
        onSelect: function(suggestion) {
            console.log(suggestion);
        }
    });
</script>

Параметр token — это API-ключ.

Демонстрация

Выберите вариант из списка, чтобы увидеть полный текст ответа в JSON:

Также работает через API

Что в ответе

Аргумент suggestion функции onSelect выглядит так:

Название Описание
Базовые поля, заполняются для всех тарифов
valueАдрес одной строкой (как показывается в списке подсказок)
unrestricted_valueАдрес одной строкой (полный, с индексом)
data.postal_codeИндекс
data.countryСтрана
data.country_iso_codeISO-код страны (двухсимвольный)
data.federal_districtФедеральный округ
data.region_fias_idФИАС-код региона
data.region_kladr_idКЛАДР-код региона
data.region_iso_codeISO-код региона
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.sub_area_fias_idФИАС-код мун. поселения
data.sub_area_kladr_idКЛАДР-код мун. поселения
data.sub_area_with_typeМун. поселение с типом
data.sub_area_typeТип мун. поселения (сокращенный)
data.sub_area_type_fullТип мун. поселения
data.sub_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.street_fias_idФИАС-код улицы
data.street_kladr_idКЛАДР-код улицы
data.street_with_typeУлица с типом
data.street_typeТип улицы (сокращенный)
data.street_type_fullТип улицы
data.streetУлица
data.stead_fias_idФИАС-код земельного участка
data.stead_kladr_idКЛАДР-код земельного участка
data.stead_type = «уч»
data.stead_type_full = «участок»
data.steadномер земельного участка
data.house_fias_idФИАС-код дома
data.house_kladr_idКЛАДР-код дома
data.house_typeТип дома (сокращенный)
data.house_type_fullТип дома
data.houseДом
data.block_typeТип корпуса/строения (сокращенный)
data.block_type_fullТип корпуса/строения
data.blockКорпус/строение
data.entrance не заполняется
data.floor не заполняется
data.flat_fias_idФИАС-код квартиры
data.flat_typeТип квартиры (сокращенный)
data.flat_type_fullТип квартиры
data.flatКвартира
data.room_fias_idФИАС-код комнаты
data.room_typeТип комнаты (сокращенный)
data.room_type_fullТип комнаты
data.roomКомната
data.postal_boxАбонентский ящик
data.fias_id

ФИАС-код (он же код ГАР) адреса для России.
Идентификатор OpenStreetMap для Беларуси, Казахстана и Узбекистана.
Для остальных стран — идентификатор объекта в базе GeoNames.

data.fias_code Не заполняется, используйте fias_id
data.fias_level Уровень детализации, до которого адрес найден в ФИАС (ГАР):
  0 — страна
  1 — регион
  3 — район
  4 — город
  5 — район города
  6 — населенный пункт
  7 — улица
  8 — дом
  9 — квартира или комната
 65 — планировочная структура
 75 — земельный участок
 -1 — иностранный или пустой
data.kladr_idКЛАДР-код
data.geoname_id Идентификатор объекта в базе GeoNames. Для российских адресов не заполняется.
data.capital_marker Признак центра района или региона:
  1 — центр района
      (Московская обл, Одинцовский р-н, г Одинцово)
  2 — центр региона
      (Новосибирская обл, г Новосибирск)
  3 — центр района и региона
      (Томская обл, г Томск)
  4 — центральный район региона
      (Тюменская обл, Тюменский р-н)
  0 — ничего из перечисленного
      (Московская обл, г Балашиха)
data.okatoКод ОКАТО
data.oktmoКод ОКТМО
data.tax_officeКод ИФНС для физических лиц
data.tax_office_legalКод ИФНС для организаций
data.history_values[ ] Список исторических названий объекта нижнего уровня.
Если подсказка до улицы — это прошлые названия этой улицы, если до города — города.
Дополнительные поля, заполняются в зависимости от тарифа
Заполняются при выборе конкретной подсказки. До этого они пустые.
Все тарифы
data.geo_latКоординаты: широта
data.geo_lonКоординаты: долгота
data.qc_geo Код точности координат:
  0 — точные координаты
  1 — ближайший дом
  2 — улица
  3 — населенный пункт
  4 — город
  5 — координаты не определены
data.fias_actuality_state Признак актуальности адреса в ФИАС
  0    — актуальный
  1–50 — переименован
  51   — переподчинен
  99   — удален
data.city_areaАдминистративный округ (только для Москвы)
«Расширенный» и «Максимальный»
data.beltway_hitВнутри кольцевой?
data.beltway_distanceРасстояние от кольцевой в километрах
Только «Максимальный»
data.stead_cadnumКадастровый номер земельного участка
data.house_cadnumКадастровый номер дома
data.flat_cadnumКадастровый номер квартиры
data.room_cadnumКадастровый номер комнаты
data.house_flat_countКоличество квартир в доме
data.flat_areaПлощадь квартиры
data.square_meter_priceРыночная стоимость м²
data.flat_priceРыночная стоимость квартиры
data.timezoneЧасовой пояс
data.metro[ ] Список ближайших станций метро (до трёх штук)
└ name— название станции
└ line— название линии
└ distance— расстояние до станции в километрах
Зарезервированы для автоматической обработки адресов через API стандартизации
data.qc_complete не заполняется
data.qc_house не заполняется
data.qc не заполняется
data.source не заполняется
data.unparsed_parts не заполняется

Административное и муниципальное деление

Подсказки могут возвращать адрес в административном либо в муниципальном делении. Это регулирует параметр запроса division (виджет / API):

  • administrative — административное;
  • municipal — муниципальное.

Если параметр не задан, используется административное деление.

В муниципальном делении возвращаются поля area* (муниципальный район) и sub_area* (муниципальное поселение). Поля city_district* (административный район города), напротив, скрываются.

В административном делении возвращаются поля area* (административный район региона) и city_district* (административный район города). Поля sub_area* (муниципальное поселение), напротив, скрываются.

Координаты, площадь и стоимость

Координаты есть у 97% домов в Москве, 91% в Санкт-Петербурге, 69% в других городах-миллиониках и 47% по остальной России.

Площадь и стоимость есть у 70% квартир в России.

Источники данных

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

Справочник индексов Почты России

Gazetteer Data и Postal Code Data от GeoNames

OpenStreetMap

ISO 3166

Примеры настройки

Подсказки отдельными полями:

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

Разложить адрес по полям: индекс, регион, город, улица, дом, квартира

Иностранные адреса или адреса на английском

Муниципальное деление

Всё что угодно ещё

Ограничения

Для иностранных адресов заполнен ограниченный набор полей, вне зависимости от тарифного плана: почтовый индекс, страна, регион, населенный пункт, часовой пояс и геокоординаты. Прочие поля — пустые.

На бесплатном тарифе плагин подсказок показывает логотип «Дадаты» в углу выпадающего списка. На платных тарифах и в «коробке» логотипа нет.

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

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

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

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

По адресам

Почему индекс неправильный — не такой, как у Почты России?

Дадата работает по объединенному справочнику налоговой службы ФИАС (ГАР) и Почты России. В нем исправлены более 7 000 некорректных и отсутствующих индексов.

К сожалению, справочник индексов Почты детализирован только до населенных пунктов. Привязки к улицам и домам нет. Поэтому все-все индексы исправить не удалось.

Если получили от Дадаты неправильный индекс — отправьте адрес через специальную форму. Мы исправляем ошибки ежемесячно.

Почему подсказки не возвращают геокоординаты и район города?

Подсказки возвращают геокоординаты и район после того, как человек выбрал конкретный адрес из списка.

В API это запрос с параметром count = 1.

Почему у дома неправильные координаты?

Если Подсказки не знают координат дома — они вернут координаты улицы. Если не знают координат улицы — вернут координаты центра города. Точность координат — в поле qc_geo.

Мы регулярно пополняем справочники. Если встретили неточные координаты — отправьте адрес через специальную форму.

Почему подсказки не возвращают площадь квартиры, ближайшее метро и часовой пояс?

Эти поля возвращаются только для тарифа «Максимальный».

Причём после того, как человек выбрал конкретный адрес из списка. В API это запрос с параметром count = 1.

Почему на картах дом есть, а в подсказках — нет?

Подсказки используют справочник адресов налоговой службы. В нем нет некоторых реально существующих домов и строений. К сожалению, более полной базы в стране просто не существует.

Чтобы добавить дом в подсказки, отправьте его через специальную форму

Поддерживаете ли вы государственный адресный реестр (ГАР)?

Да. Значение в поле fias_id — это код адреса согласно ГАР (object GUID). В ГАР есть еще целочисленный код (object ID), но регулятор его не требует, так что «Дадата» его не возвращает.

Как часто обновляется справочник адресов?

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

Общие

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

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

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

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

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

Стоимость

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