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

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

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

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

  1. Зарегистрируйтесь и получите API-ключ
  2. Вставьте код из примера на свой сайт.
  3. Profit!
<input id="address" name="address" type="text" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
<link href="https://cdn.jsdelivr.net/npm/suggestions-jquery@19.8.0/dist/css/suggestions.min.css" rel="stylesheet" />
<script src="https://cdn.jsdelivr.net/npm/suggestions-jquery@19.8.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-ключ.

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

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

Что в ответе

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

Название Описание
Базовые поля, заполняются для всех тарифов
value Адрес одной строкой (как показывается в списке подсказок)
unrestricted_value Адрес одной строкой (полный, от региона)
data.postal_code Индекс
data.country Страна
data.country_iso_code ISO-код страны (двухсимвольный)
data.federal_district Федеральный округ
data.region_fias_id Код ФИАС региона
data.region_kladr_id Код КЛАДР региона
data.region_iso_code ISO-код региона
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.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_type_full Тип дома
data.house Дом
data.block_type Тип корпуса/строения (сокращенный)
data.block_type_full Тип корпуса/строения
data.block Корпус/строение
data.flat_type Тип квартиры (сокращенный)
data.flat_type_full Тип квартиры
data.flat Квартира
data.postal_box Абонентский ящик
data.fias_id Код ФИАС:
  • HOUSE.HOUSEGUID, если дом найден в ФИАС по точному совпадению;
  • ADDROBJ.AOGUID в противном случае.
data.fias_level Уровень детализации, до которого адрес найден в ФИАС:
  0 — страна
  1 — регион
  3 — район
  4 — город
  5 — район города
  6 — населенный пункт
  7 — улица
  8 — дом
 65 — планировочная структура
 -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_code Иерархический код адреса в ФИАС (СС+РРР+ГГГ+ППП+СССС+УУУУ+ДДДД)
data.fias_actuality_state Признак актуальности адреса в ФИАС
  0    — актуальный
  1–50 — переименован
  51   — переподчинен
  99   — удален
data.city_area Административный округ (только для Москвы)
«Расширенный» и «Всё включено»
data.beltway_hit Внутри кольцевой?
data.beltway_distance Расстояние от кольцевой в километрах
Только «Всё включено»
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.unparsed_parts
Не используются
data.source

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

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

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

Ограничения

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

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

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

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

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

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

По адресам

Как сделать гранулярные подсказки по адресу? Чтобы отдельно город, улица, дом?

Пример: регион, город, улица и дом

Пример: город и улица

Пример: все поля

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

Пример: разложить адрес по полям

Как подсказывать только внутри конкретного города или области?

Пример: ограничить сектор поиска по адресу

Как подсказывать только город?

Пример: подсказки по городам

Пример: подсказки по городам и населенным пунктам

Как заставить подсказки учитывать местонахождение пользователя?

Подсказки делают это «из коробки»: определяют город пользователя по IP-адресу и подсказывают ближайшие варианты.

Как отключить геолокацию?

Передайте параметр geoLocation = false.

Как подсказывать иностранные адреса?

Передайте параметр country = "*"

Как сделать всё что угодно ещё?

Вот примеры на все случаи жизни


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

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

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

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

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

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

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

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

Эти поля возвращаются только для тарифа «Всё включено».

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

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

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

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

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

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

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

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

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

Мы рекомендуем для идентификации адреса использовать код ФИАС до улицы + дом + квартиру. И на всякий случай сохранять текстовый адрес.

Подробности в статье на Хабре


Есть ли подсказки по адресам Украины, Белоруссии и Казахстана?

Да, есть. Чтобы их включить, передайте параметр country = "*"

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

В течение двух дней после выхода обновления в налоговой. При условии, что в налоговой ничего не разломали (это случается).

Общие

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

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

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

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

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

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

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

Например, если вы владелец интернет-магазина myshop.ru, то привязка ключа к этому домену запретит пользоваться им на всех остальных сайтах.

Привязка API-ключа к домену настраивается в личном кабинете.

Стоимость

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

ajax-spinner

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

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

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

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

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