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

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

Ищет адреса по любой части адреса от региона до квартиры («самара авроры 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. Зарегистрируйтесь и получите API-ключ
  2. Вставьте код из примера на свой сайт.
  3. 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="https://cdn.jsdelivr.net/npm/suggestions-jquery@21.12.0/dist/css/suggestions.min.css" rel="stylesheet" />
<script src="https://cdn.jsdelivr.net/npm/suggestions-jquery@21.12.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_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.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.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 тысяч запросов в день. Больше — в составе годовой подписки.

ajax-spinner